Using the Document Store

This page explains everything you need to know when developing a Cloud Function that makes use of the Document Store.

What is the Document Store?

A Document Store is a database that can store data that you would want your Cloud Function to keep over time. For example, if you want your Cloud Function to register and store what actions each user takes, you could store this in the document store. Each Cloud Function has its own separate store and can only read and write data to its own store. A Cloud Function can only access a single store. The document store can accept any data in JSON format. This means that if you store documents in the store, you must ensure that your data can be converted to JSON.

A local document store is automatically provided for you when you develop your Cloud Function.

πŸ“˜

Store Availability

  • The store isn't available from the developer web form.
  • When developing the local store is reset at each restart.
  • The store is only available from ixoncdkingress>=0.0.10

When starting your Cloud Function, you should see the following messages:

ixoncdkingress - INFO - Starting DocumentDB server
ixoncdkingress - INFO - DocumentDB server started successfully

These messages show that the document store has successfully started and can be used in your Cloud Function.

How to use the DocumentDBClient

The DocumentDBClient can be extracted from the Cloud Function Context by accessing document_db_client from the context:

from ixoncdkingress.function.context import FunctionContext

@FunctionContext.expose
def document_test_entrypoint(context: FunctionContext):
    print(context.document_db_client)

From here you can perform a variety of functions to create, read, update and delete documents in your document store.

🚧

Nullability

As mentioned above, the store is not always available. So the document_db_client can be None. Be sure to check for this when developing your Cloud Function.

The DocumentDBClient contains the following functions:

FunctionParametersDescriptionMinimal ixoncdkingress version
insert_onedocument: DictInserts a single document into the store0.0.10
insert_manydocument: Iterable[Dict]Inserts multiple documents into the store0.0.10
update_onefilter_map: Mapping, update: MappingUpdates a single document from the store0.0.10
update_manyfilter_map: Mapping, update: MappingUpdates multiple documents from the store0.0.10
delete_onefilter_map: MappingRemoves one document from the store0.0.10
delete_manyfilter_map: MappingRemoves multiple documents from the store0.0.10
find_onefilter_map: MappingSame as find but only returns a single document0.0.10
findfilter_map: MappingPerform a query on the database with a specific filter0.0.10
switch_collectioncollection_name: Optional[str]Switch to another collection. When collection_name is None or an empty string, the default collection is used0.0.17

🚧

Multiple collections

The document store has one collection by default. When you want to use multiple collections, please send an email to [email protected] to have them configured and provide the following details:

  • The backend-component-template ID.
  • The name(s) of the collection(s) you want to use.

The filter_map can be used to find specific documents by their keys, while the update Mapping can be used to update specific keys of one or more documents. Here is an example of some of the functions you can use:

from ixoncdkingress.function.context import FunctionContext

@FunctionContext.expose
def document_find_text(context: FunctionContext, id: int) -> Optional[Dict[str, Any]]:
    # Find one document by its ID
    return context.document_db_client.find_one(filter_map={'id': id})

@FunctionContext.expose
def document_find_all(context: FunctionContext) -> List[Dict[str, Any]]:
    # Find all documents in the store
    return context.document_db_client.find()

@FunctionContext.expose
def document_add_or_update_text(context: FunctionContext, id: int, text: str) -> None:
    found = document_find_text(context, id)

    # If document already exists update the text by the ID
    # otherwise insert a new document
    if found is not None:
        context.document_db_client.update_one({'id': id}, {'text': text})
    else:
        context.document_db_client.insert_one({'id': id, 'text': text})

@FunctionContext.expose
def document_insert_many(context: FunctionContext, *texts: Tuple[int, str]) -> None:
    # Create a list of dictionaries from the given tuples
    documents = [
        {'id': idx, 'text': text}
        for idx, text in texts
    ]

    # Insert multiple documents at once
    context.document_db_client.insert_many(documents)

From here, you can play around with inserting, reading, updating and deleting documents.


What’s Next

To read more about advanced document querying please read: