Field Names with Periods and Dollar Signs

MongoDB allows field names that contain dollar signs ($) or periods (.). However, use of these characters within field names is discouraged, because MongoDB does not support some features with these fields.

In most cases data that has been stored using field names like these is not directly accessible. You need to use helper methods like $getField, $setField, and $literal in queries that access those fields.

The field name validation rules are not the same for all types of storage operations.

General Restrictions

There are some general restrictions on using dollar ($) prefixed field names or field names that contain a period (.). These fields cannot:

Be indexed
Be used as part of a shard key
Be validated using $jsonSchema
Be modified with an escape sequence
Be used with Field Level Encryption
Be used as a subfield in an _id document

Warning

Possible Data Loss With Dollar Signs ($) and Periods (.)

There is a small chance of data loss when using dollar ($) prefixed field names or field names that contain periods (.) if these field names are used in conjunction with unacknowledged writes (write concern w=0) on servers that are older than MongoDB 5.0.

When running insert, update, and findAndModify commands, drivers that are 5.0 compatible remove restrictions on using documents with field names that are dollar ($) prefixed or that contain periods (.). These field names generated a client-side error in earlier driver versions.

The restrictions are removed regardless of the server version the driver is connected to. If a 5.0 driver sends a document to an older server, the document will be rejected without sending an error.

Warning

Import and Export Concerns With Dollar Signs ($) and Periods (.)

Starting in MongoDB 5.0, document field names can be dollar ($) prefixed and can contain periods (.). However, mongoimport and mongoexport may not work as expected in some situations with field names that make use of these characters.

MongoDB Extended JSON v2 cannot differentiate between type wrappers and fields that happen to have the same name as type wrappers. Do not use Extended JSON formats in contexts where the corresponding BSON representations might include dollar ($) prefixed keys. The DBRef mechanism is an exception to this general rule.

There are also restrictions on using mongoimport and mongoexport with periods (.) in field names. Since CSV files use the period (.) to represent data hierarchies, a period (.) in a field name will be misinterpreted as a level of nesting.

Learn More

For examples of how to handle field names that contain periods and dollar signs, see these pages:

Back

Distributed Queries

Dollar Signs