API Reference

A BSON represents a document in Binary JSON format, defined at http://bsonspec.org/.

In Julia, you can manipulate a BSON instance just like a Dict.

Example

bson = Mongoc.BSON()
bson["name"] = "my name"
bson["num"] = 10.0

C API

BSON is a wrapper for C struct bson_t.

A BSONObjectId represents a unique identifier for a BSON document.

Example

The following generates a new BSONObjectId.

julia> Mongoc.BSONObjectId()

C API

BSONObjectId instances addresses are passed to libbson/libmongoc API using Ref(oid), and are owned by the Julia process.

Mirrors C struct bson_oid_t:

typedef struct {
   uint8_t bytes[12];
} bson_oid_t;

BSONCode is a BSON element with JavaScript source code.

Example

julia> bson = Mongoc.BSON("source" => Mongoc.BSONCode("function() = 1"))
BSON("{ "source" : { "$code" : "function() = 1" } }")

as_json(bson::BSON; canonical::Bool=false) :: String

Converts a bson object to a JSON string.

Example

julia> document = Mongoc.BSON("{ "hey" : 1 }")
BSON("{ "hey" : 1 }")

julia> Mongoc.as_json(document)
"{ "hey" : 1 }"

julia> Mongoc.as_json(document, canonical=true)
"{ "hey" : { "$numberInt" : "1" } }"

C API

• bson_as_canonical_extended_json

• bson_as_relaxed_extended_json

as_dict(document::BSON) :: Dict{String}

Converts a BSON document to a Julia Dict.

get_array(doc::BSON, key::AbstractString, ::Type{T})

Get an array from the document with a specified type T. This allows obtaining a type-stable return value. Note that if an array element cannot be converted to the specified type, an error will be thrown.

read_bson(io::IO) :: Vector{BSON}

Reads all BSON documents from io. This method will continue to read from io until it reaches eof.

read_bson(data::Vector{UInt8}) :: Vector{BSON}

Parses a vector of bytes to a vector of BSON documents. Useful when reading BSON as binary from a stream.

read_bson(filepath::AbstractString) :: Vector{BSON}

Reads all BSON documents from a file located at filepath.

This will open a Mongoc.BSONReader pointing to the file and will parse file contents to BSON documents.

read_bson(reader::BSONReader) :: Vector{BSON}

Reads all BSON documents from a reader.

write_bson(io::IO, bson::BSON;
    initial_buffer_capacity::Integer=DEFAULT_BSON_WRITER_BUFFER_CAPACITY)

Writes a single BSON document to io in binary format.

write_bson(io::IO, bson_list::Vector{BSON};
    initial_buffer_capacity::Integer=DEFAULT_BSON_WRITER_BUFFER_CAPACITY)

Writes a vector of BSON documents to io in binary format.

Example

list = Vector{Mongoc.BSON}()

let
    src = Mongoc.BSON()
    src["id"] = 1
    src["name"] = "1st"
    push!(list, src)
end

let
    src = Mongoc.BSON()
    src["id"] = 2
    src["name"] = "2nd"
    push!(list, src)
end

open("documents.bson", "w") do io
    Mongoc.write_bson(io, list)
end

read_next_bson(reader::BSONReader) :: Union{Nothing, BSON}

Reads the next BSON document available in the stream pointed by reader. Returns nothing if reached the end of the stream.

BSONError is the default Exception for BSON/MongoDB function call errors.

C API

Mirrors C struct bson_error_t.

BSONError instances addresses are passed to libbson/libmongoc API using Ref(error), and are owned by the Julia process.

typedef struct {
   uint32_t domain;
   uint32_t code;
   char message[504];
} bson_error_t;

Wrapper for bsonvaluet.

See Mongoc.get_as_bson_value.

get_as_bson_value(doc, key) :: BSONValue

Returns a value stored in a bson document doc as a BSONValue.

See also Mongoc.BSONValue.

read_bson_from_json(filepath::AbstractString) :: Vector{BSON}

Reads a JSON file into a list of BSON documents. The file should contain a sequence of valid JSON documents.

Example of a valid JSON file

{ "num" : 1, "str" : "two" }
{ "num" : 2, "str" : "three" }

Client(host, port)
Client(uri)
Client()
Client(pool; [try_pop=false])

Creates a Client, which represents a connection to a MongoDB database.

See also Mongoc.ClientPool.

Examples:

These lines are equivalent.

c = Mongoc.Client()
c = Mongoc.Client("localhost", 27017)
c = Mongoc.Client("mongodb://localhost:27017")

set_appname!(client::Client, appname::String)

Sets the application name for this client.

This string, along with other internal driver details, is sent to the server as part of the initial connection handshake.

C API

• mongoc_client_set_appname.

ping(client::Client) :: BSON

Pings the server, testing wether it is reachable.

One thing to keep in mind is that operations on MongoDB are lazy, which means that a client reaches a server only when it needs to transfer documents.

Example

julia> client = Mongoc.Client() # nothing happens here between client and server
Client(URI("mongodb://localhost:27017"))

julia> Mongoc.ping(client) # connection to server happens here
BSON("{ "ok" : 1.0 }")

get_server_mongodb_version(client::Client) :: VersionNumber

Queries the version for the MongoDB server instance.

find_databases(client::Client; options::Union{Nothing, BSON}=nothing) :: Cursor

Queries for databases.

get_database_names(client::Client; options::Union{Nothing, BSON}=nothing) :: Vector{String}

Helper method to get a list of names for all databases.

See also Mongoc.find_databases.

has_database(client::Client, database_name::String;
    options::Union{Nothing, BSON}=nothing) :: Bool

Helper method to check if there is a database named database_name.

See also Mongoc.find_databases.

ClientPool(uri; [max_size])

Creates a pool of connections to a MongoDB instance.

Example

const REPLICA_SET_URL = "mongodb://127.0.0.1:27021,127.0.0.1:27022,127.0.0.1:27023/?replicaSet=rs0"

pool = Mongoc.ClientPool(REPLICA_SET_URL, max_size=2)

# create Clients from a pool
client1 = Mongoc.Client(pool)
client2 = Mongoc.Client(pool)

When you reach the maximum number of clients, the next call to Mongoc.Client(pool) will block until a Client is released.

Use try_pop=true option to throw an error instead of blocking the current thread:

# will throw `AssertionError`
client3 = Mongoc.Client(pool, try_pop=true)

set_max_size(pool, max_size)

Set the maximum number of clients on the client pool.

Example

const REPLICA_SET_URL = "mongodb://127.0.0.1:27021,127.0.0.1:27022,127.0.0.1:27023/?replicaSet=rs0"
pool = Mongoc.ClientPool(REPLICA_SET_URL)

Mongoc.set_max_size(pool, 4)

command_simple(database::Database, command::BSON) :: BSON
command_simple(collection::Collection, command::BSON) :: BSON

Executes a command given by a JSON string or a BSON instance.

It returns the first document from the result cursor.

Example

julia> client = Mongoc.Client() # connects to localhost at port 27017
Client(URI("mongodb://localhost:27017"))

julia> bson_result = Mongoc.command_simple(client["admin"], "{ "ping" : 1 }")
BSON("{ "ok" : 1.0 }")

C API

• mongoc_database_command_simple

add_user(database::Database, username::String, password::String, roles::Union{Nothing, BSON},
    custom_data::Union{Nothing, BSON}=nothing)

This function shall create a new user with access to database.

Warning: Do not call this function without TLS.

remove_user(database::Database, username::String)

Removes a user from database.

has_user(database::Database, user_name::String) :: Bool

Checks if database has a user named user_name.

find_collections(database::Database; options::Union{Nothing, BSON}=nothing) :: Cursor

Queries for collections in a database.

get_collection_names(database::Database;
    options::Union{Nothing, BSON}=nothing) :: Vector{String}

Helper method to get collection names.

See also Mongoc.find_collections.

read_command(database::Database, command::BSON;
    options::Union{Nothing, BSON}=nothing) :: BSON

Issue a command with read semantics.

See http://mongoc.org/libmongoc/current/mongocdatabasereadcommandwith_opts.html.

write_command(database::Database, command::BSON;
    options::Union{Nothing, BSON}=nothing) :: BSON

Issue a command with write semantics.

See http://mongoc.org/libmongoc/current/mongocdatabasereadwritecommandwithopts.html.

find(collection::Collection, bson_filter::BSON=BSON();
    options::Union{Nothing, BSON}=nothing) :: Cursor

Executes a query on collection and returns an iterable Cursor.

Example

function find_contract_codes(collection, criteria::Dict=Dict()) :: Vector{String}
    result = Vector{String}()

    let
        bson_filter = Mongoc.BSON(criteria)
        bson_options = Mongoc.BSON("""{ "projection" : { "_id" : true }, "sort" : { "_id" : 1 } }""")
        for bson_document in Mongoc.find(collection, bson_filter, options=bson_options)
            push!(result, bson_document["_id"])
        end
    end

    return result
end

Check the libmongoc documentation for more information.

find(bucket::Bucket, bson_filter::BSON=BSON();
    options::BSON=BSON()) :: Cursor

Looks for files in GridFS bucket.

find_one(collection::Collection, bson_filter::BSON=BSON();
    options::Union{Nothing, BSON}=nothing) :: Union{Nothing, BSON}

Execute a query to a collection and returns the first element of the result set.

Returns nothing if the result set is empty.

count_documents(collection::Collection, bson_filter::BSON=BSON();
    options::Union{Nothing, BSON}=nothing) :: Int

Returns the number of documents on a collection, with an optional filter given by bson_filter.

length(collection) and Mongoc.count_documents(collection) produces the same output.

Example

result = length(collection, Mongoc.BSON("_id" => oid))

drop(database::Database, opts::Union{Nothing, BSON}=nothing)
drop(collection::Collection, opts::Union{Nothing, BSON}=nothing)

Drops database or collection.

For information about opts argument, check the libmongoc documentation for database drop or collection drop.

find_and_modify(collection::Collection, query::BSON;
    update::Union{Nothing, BSON}=nothing,
    sort::Union{Nothing, BSON}=nothing,
    fields::Union{Nothing, BSON}=nothing,
    flags::Union{Nothing, FindAndModifyFlags}=nothing,
    bypass_document_validation::Bool=false,
) :: BSON

Find documents and updates them in one go.

See Mongoc.FindAndModifyFlags for a list of accepted values for flags argument.

C API

• mongoccollectionfindandmodify.

Adds one or more flags to the FindAndModifyOptsBuilder. These flags can be ORed together, as in flags = Mongoc.FIND_AND_MODIFY_FLAG_UPSERT | Mongoc.FIND_AND_MODIFY_FLAG_RETURN_NEW.

• FIND_AND_MODIFY_FLAG_NONE: Default. Doesn’t add anything to the builder.

• FIND_AND_MODIFY_FLAG_REMOVE: Will instruct findandmodify to remove the matching document.

• FIND_AND_MODIFY_FLAG_UPSERT: Update the matching document or, if no document matches, insert the document.

• FIND_AND_MODIFY_FLAG_RETURN_NEW: Return the resulting document.

find_one_and_delete(collection::Collection, bson_filter::BSON;
    options::Union{Nothing, BSON}=nothing
) :: Union{Nothing, BSON}

Delete a document and return it.

See db.collection.findOneAndDelete for a list of accepted options.

find_one_and_replace(collection::Collection, bson_filter::BSON, bson_replacement::BSON;
    options::Union{Nothing, BSON}=nothing
) :: Union{Nothing, BSON}

Replace a document and return the original.

See db.collection.findOneAndReplace for a list of accepted options.

find_one_and_update(collection::Collection, bson_filter::BSON, bson_update::BSON;
    options::Union{Nothing, BSON}=nothing
) :: Union{Nothing, BSON}

Update a document and return the original.

See db.collection.findOneAndUpdate for a list of accepted options.

replace_one(
        collection::Collection,
        selector::BSON,
        replacement::BSON;
        options::Union{Nothing, BSON}=nothing
    )

Replace the result of querying by selector with replacement.

aggregate(collection::Collection, bson_pipeline::BSON;
    flags::QueryFlags=QUERY_FLAG_NONE,
    options::Union{Nothing, BSON}=nothing) :: Cursor

Use Mongoc.aggregate to execute an aggregation command.

Example

The following reproduces the example from the MongoDB Tutorial.

docs = [
    Mongoc.BSON("""{ "cust_id" : "A123", "amount" : 500, "status" : "A" }"""),
    Mongoc.BSON("""{ "cust_id" : "A123", "amount" : 250, "status" : "A" }"""),
    Mongoc.BSON("""{ "cust_id" : "B212", "amount" : 200, "status" : "A" }"""),
    Mongoc.BSON("""{ "cust_id" : "A123", "amount" : 300, "status" : "D" }""")
]

collection = client["my-database"]["aggregation-collection"]
append!(collection, docs)

# Sets the pipeline command
bson_pipeline = Mongoc.BSON("""
    [
        { "$match" : { "status" : "A" } },
        { "$group" : { "_id" : "$cust_id", "total" : { "$sum" : "$amount" } } }
    ]
""")

for doc in Mongoc.aggregate(collection, bson_pipeline)
  println(doc)
end

The result of the script above is:

BSON("{ "_id" : "B212", "total" : 200 }")
BSON("{ "_id" : "A123", "total" : 750 }")

QueryFlags correspond to the MongoDB wire protocol. They may be bitwise or’d together. They may modify how a query is performed in the MongoDB server.

These flags are passed as optional argument for the aggregation function Mongoc.aggregate.

This data type mirrors C struct mongoc_query_flags_t. See libmongoc docs for more information.

Constants

Mongoc.QUERY_FLAG_NONE: Specify no query flags.

Mongoc.QUERY_FLAG_TAILABLE_CURSOR: Cursor will not be closed when the last data is retrieved. You can resume this cursor later.

Mongoc.QUERY_FLAG_SLAVE_OK: Allow query of replica set secondaries.

Mongoc.QUERY_FLAG_OPLOG_REPLAY: Used internally by MongoDB.

Mongoc.QUERY_FLAG_NO_CURSOR_TIMEOUT: The server normally times out an idle cursor after an inactivity period (10 minutes). This prevents that.

Mongoc.QUERY_FLAG_AWAIT_DATA: Use with Mongoc.MONGOC_QUERY_TAILABLE_CURSOR. Block rather than returning no data. After a period, time out.

Mongoc.QUERY_FLAG_EXHAUST: Stream the data down full blast in multiple "reply" packets. Faster when you are pulling down a lot of data and you know you want to retrieve it all.

Mongoc.QUERY_FLAG_PARTIAL: Get partial results from mongos if some shards are down (instead of throwing an error).

transaction(f::Function, client::Client; session_options::SessionOptions=SessionOptions())

Use do-syntax to execute a transaction.

Transaction will be commited automatically. If an error occurs, the transaction is aborted.

The session parameter should be treated the same way as a Client: from a session you get a database, and a collection that are bound to the session.

Mongoc.transaction(client) do session
    database = session["my_database"]
    collection = database["my_collection"]
    new_item = Mongoc.BSON()
    new_item["inserted"] = true
    push!(collection, new_item)
end

MongoStreamFile(filepath;
    [flags=JL_O_RDONLY], [mode=0],
    [timeout_msec=DEFAULT_TIMEOUT_MSEC],
    [chunk_size=DEFAULT_CHUNK_SIZE])

Creates a stream from file located at filepath.

flags is the input to pass to open. Must be one of the constants defined at Base.Filesystem: Base.Filesystem.JL_O_RDONLY, Base.Filesystem.JL_O_CREAT, etc.

mode is an optional mode to pass to open.

upload(bucket::Bucket, filename::AbstractString, source::AbstractMongoStream;
    options::Union{Nothing, BSON}=nothing,
    file_id=BSONObjectId())

Uploads data from source to a GridFS file filename.

bson_file_id is a BSON document with a _id field. If _id field is not present, a BSONObjectId will be generated.

upload(bucket::Bucket, remote_filename::AbstractString, local_source_filepath::AbstractString;
    options::Union{Nothing, BSON}=nothing,
    file_id=BSONObjectId())

High-level interface to upload a local file to a GridFS bucket.

download(bucket::Bucket, file_id, target::AbstractMongoStream)

Download a GridFS file identified by file_id to target stream.

file_id may be either a BSONValue or a BSON document with an _id field.

download(bucket::Bucket, remote_file, local_filepath::AbstractString;
    flags::Integer=(Base.Filesystem.JL_O_CREAT | Base.Filesystem.JL_O_RDWR), mode::Integer=0o600

Downloads a GridFS file remote_file to local_filepath.

remote_file can be either a unique filename, or a file_id::BSONValue, or file_info::BSON.

delete(bucket::Bucket, file_id)
delete(bucket::Bucket, file_metadata::BSON)

Deletes a file from a GridFS Bucket.

open_download_stream(f, bucket, filename)
open_download_stream(bucket, filename) :: MongoIOStream

Opens a stream for reading a remote file identified by filename.

Example

Open a stream, do some work, then close it.

io = Mongoc.open_download_stream(bucket, file)
try
    tmp_str = read(io, String)
finally
    close(io)
end

Use do-syntax to ensure that the io stream will be closed in case something goes wrong.

Mongoc.open_download_stream(bucket, remote_filename) do io
    tmp_str = read(io, String)
end

open_upload_stream(bucket, file_id, filename; [options], [timeout_msec], [chunk_size]) :: MongoIOStream
open_upload_stream(bucket, filename; [options], [timeout_msec], [chunk_size]) :: MongoIOStream
open_upload_stream(bucket, file_info; [options], [timeout_msec], [chunk_size]) :: MongoIOStream

Opens a stream to upload a file to a GridFS Bucket.

file_info is a BSON document with the following fields:

• _id as an optional identifier.

• filename as the name of the file in the remote bucket.

If _id is not provided, a BSONObjectId will be generated.

Example

data = rand(UInt8, 3_000_000)
remote_filename = "uploaded.data"
io = Mongoc.open_upload_stream(bucket, remote_filename)
write(io, data)
close(io)

abort_upload(io::MongoIOStream)

Aborts the upload of a GridFS upload stream.