OpenIntegrations/docs/en/md/Instructions/MongoDB.md

id, sidebar_class_name

id	sidebar_class_name
MongoDB	MongoDB

<img src={require('../../static/img/APIs/MongoDB.png').default} width='64px' />

MongoDB

import LibraryIntro from '@site/src/components/LibraryIntro';

This section covers the library for working with MongoDB databases in 1С:Enterprise, OneScript, and CLI. This page describes all the steps required to get started.

<img src={require('../../static/img/addin.png').default} class="tipimage" />

Some functions in this library use an external component
Please review the ["About External Components"](/docs/Start/Component-requirements) section before starting work

Creating a Connection

When using any functions in this library, the first step is to initialize a connection to the MongoDB server. A connection string of the following format is used for this:

mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]

This string can be formed using the GenerateConnectionString function or obtained from other sources. Then, with its help, a connection can be initialized in one of the following ways:

• Explicitly A connection object can be explicitly created using the CreateConnection function. This object can be reused when calling multiple MongoDB functions, and the connection remains active as long as the object exists, unless the CloseConnection function is called or the connection is closed for other external reasons.

• Implicitly In addition to passing a pre-created connection, library functions also support passing a connection string as the Connection parameter. When using this approach, a connection using the specified connection string will be automatically created within the executing function and closed upon its completion.

When performing multiple sequential queries to the server, it is recommended to use a full connection obtained via the CreateConnection function.

Type Conversion

MongoDB uses a JSON-like document format, but with a much wider range of data types. Some of these types can be automatically converted by the library mechanisms during operations involving value insertion, based on value types within 1C/OneScript. Such types include:

1C Type	MongoDB Type (BSON)
String	String
Number (without fractional part)	Int64
Number (with fractional part)	Double
Boolean	Boolean
Date	DateTime
Array	Array
Structure, Map	Document
BinaryData	Binary
Undefined	Null

In addition to automatic conversion, the type of a value when passed can also be specified explicitly. To do this, the passed value must be wrapped in a structure where the Key is the type identifier and the Value is the actual data value being passed. The list of supported types and their keys is presented in the table below:

Structure/JSON Object Key	MongoDB Type (BSON)
__OPI_STRING__	String
__OPI_INT32__	Int32
__OPI_INT64__	Int64
__OPI_DOUBLE__	Double
__OPI_BOOLEAN__	Boolean
__OPI_DATETIME__	DateTime
__OPI_TIMESTAMP__	Timestamp
__OPI_OBJECTID__	ObjectID
__OPI_REGEXP__	RegularExpression
__OPI_JS__	JavaScriptCode
__OPI_SYMBOL__	Symbol
__OPI_MINKEY__	MinKey
__OPI_MAXKEY__	MaxKey
__OPI_NULL__	Null
__OPI_BINARY__	Binary

Passed values with types Structure, Map, and Array do not require type specification and are always converted to Document and Array respectively.

A more detailed example with type conversion during data insertion can be found in the description of the InsertDocuments function.

Other Features

For convenience, some additional features were also implemented during the library's development:

• Since structure keys in 1C cannot contain special characters, the frequently used symbol $ can be specified as __4.

    // __4 = $
    Example = New Structure("__4gte, __4lte", 100, 150); // $gte: 100, $lte: 150
    Filter    = New Structure("stringField,doubleField", "Text", Example);

• Data of type Binary when retrieved from MongoDB is returned as structures of the form {"__B64_BINARY__": <Base64 string value>}

• Data of types MaxKey and MinKey when retrieved from MongoDB is returned as strings <<MaxKey>> and <<MinKey>> respectively