Advanced Document Store Querying

Document ID Creation

When a new document is created, the document store automatically assigns a BSON ObjectId to the newly created document. This unique id is assigned to _id on the returned document. This means that you can filter documents based on their id by writing a query that looks for a specific _id . You can also create a unique id yourself before saving the document with the following code:

from bson.objectid import ObjectId

_id = ObjectId()

document_to_save = { '_id': _id, 'text': 'test document' }

πŸ“˜

Subdocuments

Please note that nested documents do not get an id assigned to them automatically. You can however, do this manually.

If you are receiving an _id as a str you will first need to parse the _id to the correct type before you can use it for filtering. See the following example:

from ixoncdkingress.function.context import FunctionContext
from bson.objectid import ObjectId

@FunctionContext.expose
def remove(context: FunctionContext, note_id: str):
    if context.document_db_client:
        self.document_client.delete_one({'_id': ObjectId(note_id)})

If the _id is not of an ObjectId type the document store will not recognize it and will not filter the documents correctly.

Query Operators

When writing queries for the document store you can make use of quite a couple of advanced query operators. This page contains all the different operators that we support.

Select Operators

This paragraph contains all of the operators that you can use to find and filter documents and subdocuments.

NameDescription
$andJoins query clauses with a logical AND returns all documents that match the conditions of both clauses.
$notInverts the effect of a query expression and returns documents that do not match the query expression.
$norJoins query clauses with a logical NOR returns all documents that fail to match both clauses.
$orJoins query clauses with a logical OR returns all documents that match the conditions of either clause.
$existsMatches documents that have the specified field.
$typeSelects documents if a field is of the specified type.
$allMatches arrays that contain all elements specified in the query.
$elemMatchSelects documents if element in the array field matches all the specified $elemMatch conditions.
$sizeSelects documents if the array field is a specified size.

Update Operators

This paragraph contains all of the operators that you can use to update existing documents and subdocuments.

Field Operators

These operators can be used to update specific fields of documents.

NameDescription
$currentDateSets the value of a field to current date, either as a Date or a Timestamp.
$incIncrements the value of the field by the specified amount.
$minOnly updates the field if the specified value is less than the existing field value.
$maxOnly updates the field if the specified value is greater than the existing field value.
$mulMultiplies the value of the field by the specified amount.
$renameRenames a field.
$setSets the value of a field in a document.
$setOnInsertSets the value of a field if an update results in an insert of a document. Has no effect on update operations that modify existing documents.
$unsetRemoves the specified field from a document.

Array Operators

These operators can be used to filter, find and update arrays inside individual documents.

NameDescription
$Acts as a placeholder to update the first element that matches the query condition.
$[]Acts as a placeholder to update all elements in an array for the documents that match the query condition.
$[]Acts as a placeholder to update all elements that match the arrayFilters condition for the documents that match the query condition.
$addToSetAdds elements to an array only if they do not already exist in the set.
$popRemoves the first or last item of an array.
$pullRemoves all array elements that match a specified query.
$pushAdds an item to an array.
$pullAllRemoves all matching values from an array.

Modifier Operators

These operators can be used to modify the function of other operators.

NameDescription
$eachModifies the $push and $addToSet operators to append multiple items for array updates.
$positionModifies the $push operator to specify the position in the array to add elements.
$sliceModifies the $push operator to limit the size of updated arrays.
$sortModifies the $push operator to reorder documents stored in an array.