How to work with database collections

Create collection

Creates the collection in the database to be used in the following database queries. Use this task on an initialization step, to create all necessary collections on the first server start.

Command name: db.collection.create

Additional parameters:

• options — IObject — object specifying the set of additional options for the collection creation.

{
    "ordered": [ "a", "b" ],
    "datetime": "date",
    "tags": "tags",
    "fulltext": "text",
    "language": "english"
}

Upsert

Adds the new object to the collection or updates the existed object.

Command name: db.collection.upsert

Additional parameters:

• document — IObject — object which should be inserted/updated in the DB

The Upsert command checks the existence of value of the “collection_nameID” field, if the ID field is absent it inserts the document, otherwise it updates the document. When the document is successfully inserted, the command adds the field “collection_nameID” to the document.

ITask task = IOC.resolve(
        Keys.getOrAdd("db.collection.upsert"),
        connection,
        collectionName,
        document
);
task.execute();

Insert

Adds new object to the collection.

Command name: db.collection.insert

If the document contains the field “collection_nameID” the command throws a successor of TaskPrepareException. In other cases it’s behavior is the same as of Upsert command.

It’s recommended to use Upsert if there is no strong necessity to use Insert.

Delete

Deletes the object from the collection.

Command name: db.collection.delete

Additional parameters:

• document — IObject — the object which should be deleted from the DB collection.

The object must have the field “collection_nameID” which contains the unique identifier of the document in the collection.

When this field is present in the document, it’s be tried to delete the object from the collection, the field “collection_nameID” is deleted from the document.

If the document is absent in the collection, no error appears because the absence of the document with the specified id is the target postcondition, the field “collection_nameID” is deleted from the in-memory document.

ITask task = IOC.resolve(
        Keys.getOrAdd("db.collection.delete"),
        connection,
        collectionName,
        document
);
task.execute();

GetById

Takes the document by it’s id.

Command name: db.collection.getbyid

Additional parameters:

• id — unique identifier of the document in the collection
• callback — lambda of type IAction<IObject> which receives the document got by id

If the document with such id does not exist, the TaskExecutionException is thrown.

ITask task = IOC.resolve(
        Keys.getOrAdd("db.collection.getbyid"),
        connection,
        collectionName,
        documentiId,
        (IAction<IObject>) foundDoc -> {
            try {
                System.out.println("Found by id");
                System.out.println((String) doc.serialize());
            } catch (SerializeException e) {
                throw new ActionExecuteException(e);
            }
        }
);
task.execute();

Search

Searching of the document in the collection.

Command name: db.collection.search

Additional parameters:

• criteria — search criteria for documents which should be selected from the collection, the IObject document
• callback — lambda of type IAction<IObject[]> which receives the set of selected documents

If no documents for the specified criteria were found, the callback function receives empty array.

{
    "filter": {
        "$or": [
            { "a": { "$eq": "b" } },
            { "b": { "$gt": 42 } }
        ]
    },
    "page": {
         "size": 50,
         "number": 2
    },
    "sort": [
         { "a": "asc" },
         { "b": "desc" }
     ]
}

{
    "filter":
        { "a.b.c": { "$eq": 123 } }
}

{
    "filter":
        { "finished": { "$gt": 15, "$lt": 20 } }
}

{
    "filter":
        { "status": { "$eq": "A" }, "age": { "$lt": 30 } }
}            

{
    "filter": { 
        "$fulltext": "term1 term2" 
    }
}

{
    "filter": { 
        "$fulltext": {
            "query": "term1 term2",
            "language": "english"
        } 
    }
}

{
    "filter": { 
        "$fulltext": {
            "query": {
                "$or": [ "term1",  "term2" ]
            },
            "language": "english"
        } 
    }
}

ITask task = IOC.resolve(
        Keys.getOrAdd("db.collection.search"),
        connection,
        collectionName,
        new DSObject(String.format(
            "{ " +
                "\"filter\": { \"%1$s\": { \"$eq\": \"new value\" } }," +
                "\"page\": { \"size\": 2, \"number\": 2 }," +
                "\"sort\": [ { \"%1$s\": \"asc\" } ]" +
            "}",
            testField.toString())),
        (IAction<IObject[]>) docs -> {
            try {
                for (IObject doc : docs) {
                    System.out.println("Found by " + testField);
                    System.out.println((String) doc.serialize());
                }
            } catch (SerializeException e) {
                throw new ActionExecuteException(e);
            }
        }
);
task.execute();    

Count

Counts the number of documents in the collection matching specified criteria.

Command name: db.collection.count

Additional parameters:

• criteria — search criteria for documents which should be counted in the collection, the IObject document
• callback — lambda of type IAction<Long> which receives the count of found documents

Search criteria are the same as for Search command described above. However, only filter part of it is taken.

If no documents for the specified criteria were found, the callback function receives zero.

It’s recommended to avoid to use this task because the counting can be as slow as selecting the same documents using Search task. Try to store and update the desired counter separately and explicitly.