client.pl -- A mongo DB client for Prolog.

This module provides access to a large part of the mongo DB API includig several read and write operations. Internally, libmongoc is used to interact with the database server. To this end, Prolog datastructures are translated from and into BSON format.

author: - Daniel Beßler
license: - BSD

mng_db_name(-DB) is det

Get the name of the database the client is connected to.

mng_get_db(?DB, -Collection, +DBType) is det

Get database and collection name for type of data denoted by DBType identifier. The type identifier can be choosen freely but should not conflict with another collection in the database.

Arguments:

`DB`	- The database name
`Collection`	- The collection name
`DBType`	- type identifier

mng_one_db(?DB, -Collection) is det

Get a special database collection with just one empty document. This is used for feeding just this one document into aggregate pipelines.

Arguments:

`DB`	- The database name
`Collection`	- The collection name

mng_drop(+DB, +Collection) is det

Drop a named collection. That is delete all documents it contains, and remove all references to it in the database.

Arguments:

`DB`	- The database name
`Collection`	- The collection name

mng_collection(+DB, ?Collection) is nondet

True if Collection is an existing collection in the named database.

Arguments:

`DB`	- The database name
`Collection`	- The collection name

mng_distinct_values(+DB, +Collection, +Key, -DistinctValues) is det

Find all distinct values associated to Key in the given named database collection.

Arguments:

`DB`	- The database name
`Collection`	- The collection name
`Key`	- The document key of interest
`DistinctValues`	- List of distinct values

mng_find(+DB, +Collection, +Filter, -Result) is nondet

Create a database cursor with given filter query and yield its results. The filter must be translatable into a BSON document, and be given as list datastructure as in:

mng_find(roslog, triples, ['s',['$eq',string('Obj1')]], Result)

Result is a Prolog dictionary instantiated from the JSON document returned by mongo DB.

Arguments:

`DB`	- The database name
`Collection`	- The collection name
`Filter`	- A mongo `DB` query
`Result`	- A document matching the query

mng_regex_prefix(+Prefix, -Pattern) is det

Create a regex pattern for matching entries with some prefix.

Arguments:

`Prefix`	- an atom
`Pattern`	- regex pattern for matching the prefix of values

mng_cursor_next(+Cursor, ?Dict) is semidet

Yields the next matching document of the given database cursor, if any. The matching document is encoded as Prolog dictionary.

Arguments:

`Cursor`	- The database cursor.
`Dict`	- The next matching document of the cursor.

mng_cursor_materialize(+Cursor, ?Dict) is nondet

Yields results of the given database cursor, if any. Each matching document is encoded as Prolog dictionary.

Arguments:

`Cursor`	- The database cursor.
`Dict`	- The next matching document of the cursor.

mng_index_create(+DB, +Collection, +Keys) is det

Creates a compound search index.

Arguments:

`DB`	- The database name
`Collection`	- The collection name
`Keys`	- List of keys for which an index shall be created

mng_index_create(+DB, +Indices) is det

Creates compound search indices. Indices is a list of tuples where the first argument is the name of the collection, and the second argument a list of keys passed to mng_index_create/3.

Arguments:

`DB`	- The database name
`Indices`	- Sequence of search indices

mng_get_dict(?Key, +Doc, ?PlValue) is semidet

Get a key-value pair from a dictionary. If the value is a document, it will be mapped to a Prolog dictionary. This is done recursively.

mng_dump(+DB, +Directory) is det

Dump a named database by calling the mongodump commandline tool.

Arguments:

`DB`	- the database name
`Directory`	- absolute path to output directory

mng_dump_collection(+DB, +Collection, +Directory) is det

Dump a named database collection by calling the mongodump commandline tool.

Arguments:

`DB`	- the database name
`Collection`	- The collection name
`Directory`	- absolute path to output directory

mng_restore(+DB, +Directory) is det

Restore named database by calling the mongorestore commandline tool.

Arguments:

`DB`	- the database name
`Directory`	- absolute path to output directory

mng_query_value(+Term, -Document) is semidet

Creates a query document from a query term. The input value can optionally be wrapped in a unary type term as in double(4). It can further be wrapped in a unary operator term as in <(4). In such a case, it might be useful to retrieve the actual value too. This can be achieved through ->/2 operator as in <(4)->Actual.

Arguments:

`Term`	- The query term
`Document`	- the query document

mng_unflatten(+Flat, -Nested) is det

Translates a flattened document into a nested one. Flattened documents may contain nested keys that contain a '.'. These are translated into a nested structure instead. For example: mng_unflatten(['a.b',1], [a,[b,1]]).

mng_typed_value(+Term, -TypedValue) is det

Ensure that Term includes a unary type term. For example:

mng_typed_value(foo, string(foo))

Arguments:

`Term`	- A potentially untyped value term.
`TypedValue`	- A typed value term.

mng_operator(?PlOperator, ?MngOperator) is det

A mapping between Prolog operators and mongo DB operators.

Arguments:

`PlOperator`	- A Prolog operator such as '<'
`MngOperator`	- A mongo operator such as '$lt'

mng_strip(+Term, ?Operator, ?Type, ?Value) is semidet

Strips a value term from its operator and type. For example:

mng_strip(<(double(2)), <, double, 2)

mng_strip(2, =, double, 2)

mng_strip(<(2)->X, <, double, 2)

Arguments:

`Term`	- A value term.
`Operator`	- The stripped operator or '='.
`Type`	- The stripped type or default type for value.
`Value`	- The bare value.

mng_strip_type(+Term, ?Type, ?Value) is det

Strip the type of a value term. That is, e.g. Term=int(7) in which case Type=int and Value=7. If Term is untyped, the type will be determined through the Prolog datatype of the value.

Arguments:

`Term`	- a value term
`Type`	- type atom
`Value`	- the value without type

mng_strip_operator(+Term, ?Operator, ?Stripped) is det

Strip the operator of a value term. That is, e.g. Term=(<(7)) in which case Operator='<' and Stripped=7. If Term has no operator, then equality operator is used as fallabck.

Arguments:

`Term`	- A value term
`Operator`	- The stripped operator or '='
`Stripped`	- The value term without operator

mng_strip_variable(+Term, ?Stripped) is det

Strips variable from a value term. That is, e.g. Term=(<(7)->X) in which case Stripped=(<(7)).

Arguments:

`Term`	- A value term
`Stripped`	- The value term without variable

mng_uri(-URI) is det

Get the URI connection string

mng_store(+DB, +Collection, +Document)

Stores a document in a named database collection. Document must be translatable into a BSON document, e.g. Document=[[foo,string(bar)]] would create a document with string value "bar" assigned to field with key "foo".

Arguments:

`DB`	- The database name
`Collection`	- The collection name
`Document`	- A database document

mng_remove(+DB, +Collection, +Query)

Removes all documents matching Query from a named collection. Query must be translatable into a BSON document, e.g. Query=[key,['$lt',double(2)]].

Arguments:

`DB`	- The database name
`Collection`	- The collection name
`Query`	- A query document

mng_update(+DB, +Collection, +Query, +Update)

Updates all documents in a named collection that match Query. Query und Update must be translatable into a BSON document, e.g. Query=[key,['$lt',double(2)]].

Arguments:

`DB`	- The database name
`Collection`	- The collection name
`Query`	- A query document
`Update`	- A update document or pipeline

mng_bulk_write(+DB, +Collection, +Operations)

Performs bulk operations.

Operations is a list of operation terms, each being one of:

insert(Document) (see mng_store/3)
remove(Query) (see mng_remove/3)
update(Query,Update) (see mng_update/4)

mng_watch(+DB, +Collection, +Callback, +Pipeline, -WatcherID) is det

Start a new change stream operation on given collection and filter documents with given aggregation pipeline. Callback is the name of a 2-ary predicate that is called for each event generated by the change stream, where the first argument is instantiated to an atom representing the operation type, and the second argument is a list of additional change information that depends on the operation type.

Arguments:

`DB`	- database name
`Collection`	- collection name
`Callback`	- name of the callback predicate
`Pipeline`	- aggregation pipeline
`WatcherID`	- unique identifier of the watch operation

mng_unwatch(+WatcherID)

Stop an existing change stream associated to the given identifier.

mng_cursor_create(+DB, +Collection, -Cursor) is det

Creates a new query cursor. Make sure to call mng_cursor_destroy/1 once you are done querying.

Arguments:

`DB`	- The database name
`Collection`	- The collection name
`Cursor`	- The id of a new mongo `DB` cursor

mng_cursor_destroy(+Cursor) is det

Destroys a query cursor.

Arguments:

Cursor

- A mongo DB cursor id

mng_cursor_limit(+Cursor, +Limit) is det

Limit the maximum number of documents a cursor may yield.

Arguments:

`Cursor`	- A mongo DB cursor id
`Limit`	- The maximum number of documents yielded by the cursor

mng_cursor_descending(+Cursor, +Key) is det

Configure a cursor to yield documents in descending order.

Arguments:

`Cursor`	- A mongo DB cursor id
`Key`	- The sort key

mng_cursor_ascending(+Cursor, +Key) is det

Configure a cursor to yield documents in ascending order.

Arguments:

`Cursor`	- A mongo DB cursor id
`Key`	- The sort key

mng_cursor_filter(+Cursor, +Query) is det

Appends an additional condition for documents matching the cursor. Query is a query term that must be translatable into a BSON document.

Arguments:

`Cursor`	- A mongo DB cursor id
`Query`	- A query document

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

mng_restore(Arg1, Arg2, Arg3)
mng_dump(Arg1, Arg2, Arg3)