Identifiers are used to refer to objects exposed by the driver, such as tables and columns. The driver supports both quoted and unquoted identifiers for naming objects. The maximum length of both quoted and unquoted identifiers is 128 characters. Quoted identifiers must be enclosed in double quotation marks (""). A quoted identifier can contain any Unicode character, including the space character, and is case-sensitive. The driver recognizes the Unicode escape sequence \uxxxx as a Unicode character. You can specify a double quotation mark in a quoted identifier by escaping it with a double quotation mark. Unquoted identifiers must start with an ASCII alpha character and can be followed by zero or more ASCII alpha or numeric characters.

By default, the driver exposes native objects as unquoted, uppercase identifiers when creating the relational schema of your native data. Since native objects are case sensitive in MongoDB, the driver avoids naming conflicts by appending identifiers which have the same name but different cases with an underscore separator and integer (for example, _1). If one of the conflicting names contains only uppercase characters, that name will remain unaltered. For example, if the collections Test, TEST, and test are found, the driver will expose the collections as tables in the following manner:

Table 1. Name Conflict Resolution Example
Collection Name Table Name
Test TEST_1
TEST TEST
test TEST_2

The driver allows you to change default behavior related to identifiers and manage identifiers directly through the use of the connection properties described in the following sections.

UppercaseIdentifiers property

The UppercaseIdentifiers property determines whether native objects are mapped as unquoted, uppercase identifiers (the default) or quoted, mixed case identifiers that correspond directly with native object names. Therefore, as an alternative to the driver's default behavior, you can use UppercaseIdentifiers to retain the names of native objects in the relational view of your data. When UppercaseIdentifiers is set to false, the driver maps the names of native objects as quoted identifiers, maintaining the case of native object names in the relational view of native data. If these identifiers are called in a SQL statement, the statement must enclose the identifiers in double quotation marks and they must exactly match the case of the identifier name. For example, when UppercaseIdentifiers=false, you would use the following statement to query the Account table:

SELECT "id", "name" FROM "Account"

The setting for UppercaseIdentifiers also affects the use of catalog functions. When object names are passed as arguments to catalog functions, the case of the value must match the case of the name in the database. If UppercaseIdentifiers=true (the default) when the schema map was created, the value passed to the catalog function must be uppercase because unquoted identifiers are automatically converted to uppercase by the driver. If UppercaseIdentifiers=false when the schema map was created, the value passed to the catalog function must match the case of the name as it was defined. In addition, when UppercaseIdentifiers=false, object names in results returned from catalog functions are returned in the case that they are stored in the database.

KeywordConflictSuffix property

You can use the KeywordConflictSuffix property to avoid naming conflicts when the name of an object corresponds to the name of a SQL engine keyword. KeywordConflictSuffix specifies a string of up to five alphanumeric characters that the driver appends to any object or field name that conflicts with a SQL engine keyword. For example, if you specify KeywordConflictSuffix=TAB, the driver maps the Case object to CASETAB.

LeadingUnderscoreReplacement property

The LeadingUnderscoreReplacement property allows you to replace leading underscores with a string when leading underscores are used in identifiers for collections and fields. For example, MongoDB collections automatically include the _id field. By specifying LeadingUnderscoreReplacement=XX, the _id field becomes the XXID column in the relational view of the data. In addition, any other fields or collections with a leading underscore would be modified in the same manner.

SpecialCharBehavior property

The SpecialCharBehavior property allows you to determine how the driver handles the mapping of native identifiers containing characters that would require them to be quoted in SQL statements. This property provides a method to choose to continue using identifiers that require quotation marks or for the driver to modify affected identifier names so that quotation marks are not required. By default, the driver removes any characters that are not part of a legal, unquoted SQL identifier. In practice, this removes any characters that are not letters, digits, or underscores. For example, if the native name were Cost of Customer Acquisition, the mapped name would be CostofCustomerAcquisition. The default behavior eliminates the need to quote these identifiers, but changes the identifier's name when mapping it to the relational view.

FlattenArrayBase property

When arrays are flattened into columns, the driver appends an underscore and the ordinal position to the column name (<array_name>_<oridinal_location>). You can specify the starting ordinal value, either a 0 or 1, using the FlattenArrayBase property. For example, if you specified a value of 0, the first three names of columns of an array named vehicles would be VEHICLES_0, VEHICLE_1, VEHICLE_0. The default starting ordinal value is 1.

JSONColumns property

The JSONColumns property determines whether the driver exposes complex columns as JSON values in addition to their normalized mapping. Exposing complex columns as JSON values can make certain operations more convenient, such as when tools use this data as a single object for communication. In rare instances where variations in data structure might cause this data to not be sampled, enabling this property also provides a method in which it can still be read as a JSON value. When enabled (JSONColumns=1), the driver will also expose complex columns values as JSON values, which can be returned if needed. When this property is disable (JSONColumns=0), the driver will only map complex values according to the standard normalization rules.