Документация для v 1.2

Материал из support.qbpro.ru
Версия от 13:50, 24 августа 2013; imported>Vix (Новая страница: «Документация для официального драйвера MongoDB Nodejs Official Driver v 1.2 (supported by 10gen) [https://github.com/mongodb/n…»)
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)

Документация для официального драйвера MongoDB Nodejs Official Driver v 1.2 (supported by 10gen) оригинал полной документации

Примечания для понимания взяты здесь.

MongoClient - новый улучшенный или как по новому подключится лучше

Начиная с драйвера версии 1.2 включен новый класс подключения, который имеет одинаковое название во всех официальных драйверах. Это не означает, что существующие приложения перестанут работать, просто рекомендуется использовать новые API упрощенного подключения и разработки.

В дальнейшем будет разработан новый класс MongoClient принимающий все написанное (???неточный перевод) для MongoDB в отличие от существующего класса подключения Db в котором acknowledgements выключен. 

MongoClient = function(server, options);
MongoClient.prototype.open

MongoClient.prototype.close

MongoClient.prototype.db

MongoClient.connect


Выше описан полный интерфейс MongoClient. Методы open, close and db работают аналогично существующим методам в классе (прим. переводчика: Объекте) Db. Основное отличие в том, что конструктор пропускает database name из Db. Рассмотрим простое подключение используя open, код заменит тысячи слов. 


var MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server;

var mongoClient = new MongoClient(new Server('localhost', 27017));
            
    mongoClient.open(function(err, mongoClient) {

var db1 = mongoClient.db("mydb");

    mongoClient.close();
 });

Следует обратить внимание, что настройки MongoClient такие же, как для объекта Db. Основным отличием является то, что доступ к данным происходит через метод db объекта MongoClient вместо непосредственного использования экземпляра объекта db, как было раньше. Также MongoClient поддерживает те же параметры, что и предыдущий экземпляр Db.

Таким образом, с минимальными изменениями в приложении можно применить новый объект MongoClient для подключения.

URL формат подключения

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

URL формата унифицированы во всех официальных драйверах от 10gen, некоторые опции не поддерживается сторонними драйверами в силу естественных причин.

Составные части url

  • mongodb:// - префикс запроса идентифицирующий строку как стандартный формат подключения
  • username:password@ - необязательные параметры. Если заданы, драйвер использует авторизацию для подключения к database после соединения с серером.
  • host1 - единственная обязательная часть URI. Идентифицируется каждый hostname, IP адрес или or unix сокет
  • :portX - порт подключения, необязательный параметр, по умолчанию :27017.
  • /database это имя базы данных для входа и, следовательно, имеет смысл только, если имя пользователя: пароль @ синтаксис. Если не указано "Admin" база данных будет использоваться по умолчанию.(???не понятно)
  • ?options - параметры подключения. Если значение database будет отсутствовать, то символ / должен все равно присутствовать между последним host и знаком ?, предваряющим параметры. Параметры имеют формат name=value и разделены знаком "&". Для неправильных или не поддерживаемых параметров драйвер запишет предупреждение в лог и продолжит выполнение. Драйвер не поддерживает других опций, кроме описанных в спецификации. Это делается для того, чтобы уменьшить вероятность того, что различные драйверы будут поддерживать немного измененные, но в последствие несовместимые параметры (например, другие имена, разные значения, или другое значение по умолчанию).

Параметры Replica set:

  • replicaSet=name
    • Драйвер проверяет имя replica set для подключения к машине с этим именем. Подразумевается, что hostы указаны в списке, а драйвер будет пытаться найти все элементы набора.
    • НЕТ ЗНАЧЕНИЯ ПО УМОЛЧАНИЮ.
Прим. Репликация в MongoDB работает сходным образом с репликацией в реляционных базах данных. Записи посылаются на один сервер — ведущий (master), который потом синхронизирует своё состояние с другими серверами — ведомыми (slave). Вы можете разрешить или запретить чтение с ведомых серверов, в зависимости от того, допускается ли в вашей системе чтение несогласованных данных. Если ведущий сервер падает, один из ведомых может взять на себя роль ведущего.
Хотя репликация увеличивает производительность чтения, делая его распределённым, основная её цель — увеличение надёжности. Типичным подходом является сочетание репликации и шардинга. Например, каждый шард может состоять из ведущего и ведомого серверов. (Технически, вам также понадобится арбитр, чтобы разрешить конфликт, когда два ведомых сервера пытаются объявить себя ведущими. Но арбитр потребляет очень мало ресурсов и может быть использован для нескольких шардов сразу.)

Конфигурация подключения:

  • ssl=true|false|prefer
    • true: драйвер инициирует каждое подключение и использованием SSL
    • false: драйвер инициирует каждое подключение без использования SSL
    • prefer: драйвер будет пытаться инициировать каждое подключение и использованием SSL, в случае неудачи, будет инициировано подключение без использования SSL
    • Значение по умолчанию: false.
  • connectTimeoutMS=ms
    • How long a connection can take to be opened before timing out.
    • Current driver behavior already differs on this, so default must be left to each driver. For new implementations, the default should be to never timeout.
  • socketTimeoutMS=ms
    • How long a send or receive on a socket can take before timing out.
    • Current driver behavior already differs on this, so default must be left to each driver. For new implementations, the default should be to never timeout.

Конфигурация пула подключений:

  • maxPoolSize=n: Максимальное число подключений в пуле
    • Значение по умолчанию: 100

Write concern configuration:

w=wValue

  • For numeric values above 1, the driver adds { w : wValue } to the getLastError command.
  • wValue is typically a number, but can be any string in order to allow for specifications like "majority"
  • Default value is 1.
  • If wValue == -1 ignore network errors
  • If wValue == 0 Don't send getLastError
  • If wValue == 1 send {getlasterror: 1} (no w)

wtimeoutMS=ms

  • The driver adds { wtimeout : ms } to the getlasterror command.
  • Used in combination with w
  • No default value

journal=true|false

  • true: Sync to journal.
  • false: the driver does not add j to the getlasterror command
  • Default value is false

fsync=true|false

  • true: Sync to disk.
  • false: the driver does not add fsync to the getlasterror command
  • Default value is false

If conflicting values for fireAndForget, and any write concern are passed the driver should raise an exception about the conflict.

Read Preference

slaveOk=true|false: Whether a driver connected to a replica set will send reads to slaves/secondaries.

  • Default value is false

readPreference=enum: The read preference for this connection. If set, it overrides any slaveOk value.

  • Enumerated values:
  • primary
  • primaryPreferred
  • secondary
  • secondaryPreferred
  • nearest
  • Default value is primary

readPreferenceTags=string. A representation of a tag set as a comma-separated list of colon-separated key-value pairs, e.g.dc:ny,rack:1. Spaces should be stripped from beginning and end of all keys and values. To specify a list of tag sets, using multiple readPreferenceTags, e.g. readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=

  • Note the empty value, it provides for fallback to any other secondary server if none is available
  • Order matters when using multiple readPreferenceTags
  • There is no default value

MongoClient.connect

При использовании MongoClient.connect можно (наверное нужно) использовать URL формат подключения. Где возможно, MongoClient максимально наилучшие параметры по умолчанию, но их всегда можно изменить. Это относится к параметрам auto_reconnect:trueи native_parser:true если возможно. Ниже примеры подключения к single server a replicaset and a sharded system using MongoClient.connect

Подключение к single server

var MongoClient = require('mongodb').MongoClient;

 MongoClient.connect("mongodb://localhost:27017/integration_test", function(err, db) {
   test.equal(null, err);
   test.ok(db != null);

   db.collection("replicaset_mongo_client_collection").update({a:1}, {b:1}, {upsert:true}, function(err, result) {
     test.equal(null, err);
     test.equal(1, result);

     db.close();
     test.done();
   });
 });

A replicaset connect using no ackowledgment by default and readPreference for secondary

var MongoClient = require('mongodb').MongoClient;

 MongoClient.connect("mongodb://localhost:30000,localhost:30001/integration_test_?w=0&readPreference=secondary", function(err, db) {
   test.equal(null, err);
   test.ok(db != null);

   db.collection("replicaset_mongo_client_collection").update({a:1}, {b:1}, {upsert:true}, function(err, result) {
     test.equal(null, err);
     test.equal(1, result);

     db.close();
     test.done();
   });
 });

A sharded connect using no ackowledgment by default and readPreference for secondary

var MongoClient = require('mongodb').MongoClient;

 MongoClient.connect("mongodb://localhost:50000,localhost:50001/integration_test_?w=0&readPreference=secondary", function(err, db) {
   test.equal(null, err);
   test.ok(db != null);

   db.collection("replicaset_mongo_client_collection").update({a:1}, {b:1}, {upsert:true}, function(err, result) {
     test.equal(null, err);
     test.equal(1, result);

     db.close();
     test.done();
   });
 });

Notice that when connecting to the shareded system it's pretty much the same url as for connecting to the replicaset. This is because the driver itself figures out if it's a replicaset or a set of Mongos proxies it's connecting to. No special care is needed to specify if it's one or the other. This is in contrast to having to use the ReplSet or Mongos instances when using the open command.

MongoClient.connect опции

The connect function also takes a hash of options divided into db/server/replset/mongos alowing you to tweak options not directly supported by the unified url string format. To use these options you do pass in a has like this. 

var MongoClient = require('mongodb').MongoClient;

 MongoClient.connect("mongodb://localhost:27017/integration_test_?", {
     db: {
       native_parser: false
     },
     server: {
       socketOptions: {
         connectTimeoutMS: 500
       }
     },
     replSet: {},
     mongos: {}
   }, function(err, db) {
   test.equal(null, err);
   test.ok(db != null);

   db.collection("replicaset_mongo_client_collection").update({a:1}, {b:1}, {upsert:true}, function(err, result) {
     test.equal(null, err);
     test.equal(1, result);

     db.close();
     test.done();
   });
 });

Below are all the options supported for db/server/replset/mongos.

  • db A hash of options at the db level overriding or adjusting functionaliy not suppported by the url
  • w, {Number/String, > -1 || 'majority'} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1 or w = 'majority' acknowledges the write
  • wtimeout, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
  • fsync, (Boolean, default:false) write waits for fsync before returning
  • journal, (Boolean, default:false) write waits for journal sync before returning
  • readPreference {String}, the prefered read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  • native_parser {Boolean, default:false}, use c++ bson parser.
  • forceServerObjectId {Boolean, default:false}, force server to create _id fields instead of client.
  • pkFactory {Object}, object overriding the basic ObjectID primary key generation.
  • serializeFunctions {Boolean, default:false}, serialize functions.
  • raw {Boolean, default:false}, peform operations using raw bson buffers.
  • recordQueryStats {Boolean, default:false}, record query statistics during execution.
  • retryMiliSeconds {Number, default:5000}, number of miliseconds between retries.
  • numberOfRetries {Number, default:5}, number of retries off connection.
  • server A hash of options at the server level not supported by the url.
  • readPreference {String, default:null}, set's the read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST)
  • ssl {Boolean, default:false}, use ssl connection (needs to have a mongod server with ssl support)
  • slaveOk {Boolean, default:false}, legacy option allowing reads from secondary, use readPrefrence instead.
  • poolSize {Number, default:1}, number of connections in the connection pool, set to 1 as default for legacy reasons.
  • socketOptions {Object, default:null}, an object containing socket options to use (noDelay:(boolean), keepAlive:(number), connectTimeoutMS:(number), socketTimeoutMS:(number))
  • logger {Object, default:null}, an object representing a logger that you want to use, needs to support functions debug, log, error ({error:function(message, object) {}, log:function(message, object) {}, debug:function(message, object) {}}).
  • auto_reconnect {Boolean, default:false}, reconnect on error.
  • disableDriverBSONSizeCheck {Boolean, default:false}, force the server to error if the BSON message is to big
  • replSet A hash of options at the replSet level not supported by the url.
  • ha {Boolean, default:true}, turn on high availability.
  • haInterval {Number, default:2000}, time between each replicaset status check.
  • reconnectWait {Number, default:1000}, time to wait in miliseconds before attempting reconnect.
  • retries {Number, default:30}, number of times to attempt a replicaset reconnect.
  • rs_name {String}, the name of the replicaset to connect to.
  • socketOptions {Object, default:null}, an object containing socket options to use (noDelay:(boolean), keepAlive:(number), connectTimeoutMS:(number), socketTimeoutMS:(number))
  • readPreference {String}, the prefered read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  • strategy {String, default:null}, selection strategy for reads choose between (ping and statistical, default is round-robin)
  • secondaryAcceptableLatencyMS {Number, default:15}, sets the range of servers to pick when using NEAREST (lowest ping ms + the latency fence, ex: range of 1 to (1 + 15) ms)
  • connectArbiter {Boolean, default:false}, sets if the driver should connect to arbiters or not.
  • mongos A hash of options at the mongos level not supported by the url.
  • socketOptions {Object, default:null}, an object containing socket options to use (noDelay:(boolean), keepAlive:(number), connectTimeoutMS:(number), socketTimeoutMS:(number))
  • ha {Boolean, default:true}, turn on high availability, attempts to reconnect to down proxies
  • haInterval {Number, default:2000}, time between each replicaset status check.

Database

The first thing to do in order to make queries to the database is to open one. This can be done with the Db constructor. 

var mongodb = require("mongodb"),
     mongoserver = new mongodb.Server(host, port, server_options),
     db_connector = new mongodb.Db(name, mongoserver, db_options);

 db_connector.open(callback);
  • host is a server hostname or IP
  • port is a MongoDB port, use mongodb.Connection.DEFAULT_PORT for default (27017)
  • server_options see Server options
  • name is the databse name that needs to be opened, database will be created automatically if it doesn't yet exist
  • db_options see DB options

Параметры Server

Several options can be passed to the Server constructor with options parameter.

  • auto_reconnect - to reconnect automatically, default:false
  • poolSize - specify the number of connections in the pool default:5
  • socketOptions - a collection of pr socket settings

Параметры Socket

Several options can be set for the socketOptions.

  • timeout = set seconds before connection times out default:0
  • noDelay = Отключает алгоритм Nagle default:true
Алгоритм Nagle TCP/IP был разработан, чтобы избежать проблем при передаче небольших пакетов, называемых tinygrams, в медленных сетях. Задача алгоритма балансировать нагрузку TCP соединения, т.е. он пытается равномерно "размазывать" трафик. Поэтому когда идёт активная передача небольших (менее 1500 байт) пакетов данных, алгоритм старается сгладить этот пик нагрузки, задерживая пакеты и пытаясь распределить их более равномерно по времени. Последствием работы данного алгоритма могут быть задержки в передаче пакетов до 200мс. источник 1, источник 2
  • keepAlive = Set if keepAlive is used default:0, which means no keepAlive, set higher than 0 for keepAlive
  • encoding = 'ascii'|'utf8'|'base64' default:null

DB опции

Several options can be passed to the Db constructor with options parameter.

  • native_parser - if true, use native BSON parser
  • strict - sets strict mode, if true then existing collections can't be "recreated" etc.
  • pk - custom primary key factory to generate _id values (see Custom primary keys).
  • forceServerObjectId - generation of objectid is delegated to the mongodb server instead of the driver. default is false
  • retryMiliSeconds - specify the number of milliseconds between connection attempts default:5000
  • numberOfRetries - specify the number of retries for connection attempts default:3
  • reaper - enable/disable reaper (true/false) default:false
  • reaperInterval - specify the number of milliseconds between each reaper attempt default:10000
  • reaperTimeout - specify the number of milliseconds for timing out callbacks that don't return default:30000
  • raw - driver expects Buffer raw bson document, default:false
  • logger - object specifying error(), debug() and log() functions

Подключение к database

Database может быть открыта с помощью метода open. 

db_connector.open(callback);

callback is a callback function which gets 2 parameters - an error object (or null, if no errors occured) and a database object.

Resulting database object can be used for creating and selecting collections. 

db_connector.open(function(err, db){
     db.collection(...);
 });

Свойства Database

  • databaseName is the name of the database
  • serverConfig includes information about the server (serverConfig.host, serverConfig.port etc.)
  • state indicates if the database is connected or not
  • strict indicates if strict mode is on (true) or off (false, default)
  • version indicates the version of the MongoDB database

События Database

  • close to indicate that the connection to the database was closed

Например: 

db.on("close", function(error){
     console.log("Connection to the database was closed!");
 });

NB! If auto_reconnect was set to true when creating the server, then the connection will be automatically reopened on next database operation. Nevertheless the close event will be fired.

Совместное использование соединений с несколькими базами

Для совместного использования пула соединений между несколькими базами данных экземпляр базы данных имеет метод db 

db_connector.db(name)

this returns a new db instance that shares the connections off the previous instance but will send all commands to the databasename. This allows for better control of resource usage in a multiple database scenario.

Удаление database

Для удаления database, вначале необходимо установить на неё курсор. Удаление может быть выполнено методом dropDatabase 

db_connector.open(function(err, db){
     if (err) { throw err; }
     db.dropDatabase(function(err) {
         if (err) { throw err; }
         console.log("database has been dropped!");
     });
 });

Пользовательские первичные ключи

Каждая запись в database имеет уникальный первичный ключ называющийся _id. По умолчанию первичный ключ представляет собой хэш длиной 12 байт, но пользовательский генератор ключей может это переопределить. Если установить _id вручную, то для добавляемых записей можно использовать что угодно, генератор первичных ключей (primary key factory generates) подставит автосгенерированное значение _id только для тех записей, где ключ _id не определен.

Example 1: No need to generate primary key, as its already defined: 

collection.insert({name:"Daniel", _id:"12345"});

Example 2: No primary key, so it needs to be generated before save: 

collectionn.insert({name:"Daniel"});

Custom primary key factory is actually an object with method createPK which returns a primary key. The context (value for this) forcreatePK is left untouched. 

var CustomPKFactory = {
     counter:0,
     createPk: function() {
         return ++this.counter;
     }
 } 

 db_connector = new mongodb.Db(name, mongoserver, {pk: CustomPKFactory});

Отладка

In order to debug the commands sent to the database you can add a logger object to the DB options. Make sure also the propertydoDebug is set.

Пример: 

options = {}
 options.logger = {};
 options.logger.doDebug = true;
 options.logger.debug = function (message, object) {
     // print the mongo command:
     // "writing command to mongodb"
     console.log(message);

     // print the collection name 
     console.log(object.json.collectionName)

     // print the json query sent to MongoDB
     console.log(object.json.query)

     // print the binary object
     console.log(object.binary)
 }

 var db = new Db('some_database', new Server(...), options);

Collections

Так же смотри:

Объекты-коллекции

Collection object is a pointer to a specific collection in the database. If you want to insert new records or query existing ones then you need to have a valid collection object.

Примечание Название коллекций не может начинаться или содержать знакa $ (.tes$t - is not allowed)

Создание коллекции

Collections can be created with createCollection 

db.createCollection([[name[, options]], callback)

where name is the name of the collection, options a set of configuration parameters and callback is a callback function. db is the database object.

The first parameter for the callback is the error object (null if no error) and the second one is the pointer to the newly created collection. If strict mode is on and the table exists, the operation yields in error. With strict mode off (default) the function simple returns the pointer to the existing collection and does not truncate it. 

db.createCollection("test", function(err, collection){
    collection.insert({"test":"value"});
});

Создание параметров коллекции

Several options can be passed to the createCollection function with options parameter. 

* `raw` - driver returns documents as bson binary Buffer objects, `default:false`

Collection properties

  • collectionName is the name of the collection (not including the database name as a prefix)
  • db is the pointer to the corresponding databse object

Example of usage: 

console.log("Collection name: "+collection.collectionName)

Список стандартных коллекций

Список names

Collections can be listed with collectionNames 

db.collectionNames(callback);

callback gets two parameters - an error object (if error occured) and an array of collection names as strings.

Collection names also include database name, so a collection named posts in a database blog will be listed as blog.posts.

Additionally there's system collections which should not be altered without knowing exactly what you are doing, these sollections can be identified with system prefix. For example posts.system.indexes.

Пример: 

var mongodb = require("mongodb"),
     mongoserver = new mongodb.Server("localhost"),
     db_connector = new mongodb.Db("blog", mongoserver);

 db_connector.open(function(err, db){
     db.collectionNames(function(err, collections){
         <nowiki>console.log(collections); // ["blog.posts", "blog.system.indexes"]
    });
});</nowiki>

Список collections

Collection objects can be listed with database method collections 

db.collections(callback)

Where callback gets two parameters - an error object (if an error occured) and an array of collection objects.

Выбор collections

Созданная коллекция может быть открыта при помощи метода collection 

db.collection([[name[, options]], callback);

Если strict mode выключен, тогда в случае отсутствия коллекции, новая коллекция создастся автоматически.

Selecting collections options

Several options can be passed to the collection function with options parameter.

  • `raw` - driver returns documents as bson binary Buffer objects, `default:false`

Renaming collections

A collection can be renamed with collection method rename 

collection.rename(new_name, callback);

Removing records from collections

Records can be erased from a collection with remove 

collection.remove([[query[, options]], callback]);

Where

  • query is the query that records to be removed need to match. If not set all records will be removed
  • options indicate advanced options. For example use {safe: true} when using callbacks
  • callback callback function that gets two parameters - an error object (if an error occured) and the count of removed records

Removing collections

A collection can be dropped with drop 

collection.drop(callback);

or with dropCollection 

db.dropCollection(collection_name, callback)

Inserting and updating

See also:

Insert

Records can be inserted to a collection with insert 

collection.insert(docs[, options, callback])

Where

  • docs is a single document object or an array of documents
  • options is an object of parameters, if you use a callback, set safe to true - this way the callback is executed after the record is saved to the database, if safe is false (default) callback is fired immediately and thus doesn't make much sense.
  • callback - callback function to run after the record is inserted. Set safe to true in options when using callback. First parameter for callback is the error object (if an error occured) and the second is an array of records inserted.

For example 

var document = {name:"David", title:"About MongoDB"};
collection.insert(document, {safe: true}, function(err, records){
    console.log("Record added as "+records[0]._id);
});

If trying to insert a record with an existing _id value, then the operation yields in error. 

collection.insert({_id:1}, {safe:true}, function(err, doc){
    // no error, inserted new document, with _id=1
    collection.insert({_id:1}, {safe:true}, function(err, doc){
        // error occured since _id=1 already existed
    });
});

Save

Shorthand for insert/update is save - if _id value set, the record is updated if it exists or inserted if it does not; if the _id value is not set, then the record is inserted as a new one. 

collection.save({_id:"abc", user:"David"},{safe:true}, callback)

callback gets two parameters - an error object (if an error occured) and the record if it was inserted or 1 if the record was updated.

Update

Updates can be done with update 

collection.update(criteria, update[, options[, callback]]);

Where

  • criteria is a query object to find records that need to be updated (see Queries)
  • update is the replacement object
  • options is an options object (see below)
  • callback is the callback to be run after the records are updated. Has two parameters, the first is an error object (if error occured), the second is the count of records that were modified.

Update options

There are several option values that can be used with an update

  • safe - run callback only after the update is done, defaults to false
  • multi - update all records that match the query object, default is false (only the first one found is updated)
  • upsert - if true and no records match the query, insert update as a new record
  • raw - driver returns updated document as bson binary Buffer, default:false

Replacement object

If the replacement object is a document, the matching documents will be replaced (except the _id values if no _id is set). 

collection.update({_id:"123"}, {author:"Jessica", title:"Mongo facts"});

The example above will replace the document contents of id=123 with the replacement object.

To update only selected fields, $set operator needs to be used. Following replacement object replaces author value but leaves everything else intact. 

collection.update({_id:"123"}, {$set: {author:"Jessica"}});

See MongoDB documentation for all possible operators.

Find and Modify

To update and retrieve the contents for one single record you can use findAndModify. 

collection.findAndModify(criteria, sort, update[, options, callback])

Where

  • criteria is the query object to find the record
  • sort indicates the order of the matches if there's more than one matching record. The first record on the result set will be used. See Queries->find->options->sort for the format.
  • update is the replacement object
  • options define the behavior of the function
  • callback is the function to run after the update is done. Has two parameters - error object (if error occured) and the record that was updated.

Options

Options object can be used for the following options:

  • remove - if set to true (default is false), removes the record from the collection. Callback function still gets the object but it doesn't exist in the collection any more.
  • new - if set to true, callback function returns the modified record. Default is false (original record is returned)
  • upsert - if set to true and no record matched to the query, replacement object is inserted as a new record

Example

var mongodb = require('mongodb'),
     server = new mongodb.Server("127.0.0.1", 27017, {});

 new mongodb.Db('test', server, {}).open(function (error, client) {
     if (error) throw error;
     var collection = new mongodb.Collection(client, 'test_collection');
     collection.findAndModify(
         {hello: 'world'}, // query
         <nowiki>[['_id','asc']],  // sort order
        {$set: {hi: 'there'}}, // replacement, replaces only the field "hi"
        {}, // options
        function(err, object) {
            if (err){
                console.warn(err.message);  // returns error if no matching object found
            }else{
                console.dir(object);
            }
        });
    });

</nowiki>

Queries

See also:

Выполнение запросов при помощи find()

Collections can be queried with find. 

collection.find(query[[[, fields], options], callback]);

Where

  • query - is a query object, defining the conditions the documents need to apply
  • fields - indicates which fields should be included in the response (default is all)
  • options - defines extra logic (sorting options, paging etc.)
  • raw - driver returns documents as bson binary Buffer objects, default:false

The result for the query is actually a cursor object. This can be used directly or converted to an array. 

var cursor = collection.find({});
cursor.each(...);

To indicate which fields must or must no be returned fields value can be used. For example the following fields value 

{
    "name": true,
    "title": true
}

retrieves fields name and title (and as a default also _id) but not any others.

Find first occurence with findOne()

findOne is a convinence method finding and returning the first match of a query while regular find returns a cursor object instead. Use it when you expect only one record, for example when querying with _id or another unique property. 

collection.findOne([query], callback)

Where

  • query is a query object or an _id value
  • callback has two parameters - an error object (if an error occured) and the document object.

Example: 

collection.findOne({_id: doc_id}, function(err, document) {
    console.log(document.name);
});

Значения _id

Default _id values are 12 byte binary hashes. You can alter the format with custom Primary Key factories (see Custom Primarky Keys in Database).

In order to treat these binary _id values as strings it would be wise to convert binary values to hex strings. This can be done withtoHexString property. 

var idHex = document._id.toHexString();

Hex strings can be reverted back to binary (for example to perform queries) with ObjectID.createFromHexString 

{_id: ObjectID.createFromHexString(idHex)}

When inserting new records it is possible to use custom _id values as well which do not need to be binary hashes, for example strings. 

collection.insert({_id: "abc", ...});
collection.findOne({_id: "abc"},...);

This way it is not necessary to convert _id values to hex strings and back.

Объект Query

The simplest query object is an empty one {} which matches every record in the database.

To make a simple query where one field must match to a defined value, one can do it as simply as 

{fieldname: "fieldvalue"}

This query matches all the records that a) have fields called fieldname and b) its value is "fieldvalue".

For example if we have a collection of blog posts where the structure of the records is {title, author, contents} and we want to retrieve all the posts for a specific author then we can do it like this: 

posts = pointer_to_collection;
posts.find({author:"Daniel"}).toArray(function(err, results){
    console.log(results); // output all records
});

If the queried field is inside an object then that can be queried also. For example if we have a record with the following structure: 

{
    user: {
        name: "Daniel"
    }
}

Then we can query the "name" field like this: {"user.name":"Daniel"}

AND

If more than one fieldname is specified, then it's an AND query 

{
    key1: "value1",
    name2: "value2"
}

Whis query matches all records where key1 is "value1" and key2 is "value2"

OR

OR queries are a bit trickier but doable with the $or operator. Query operator takes an array which includes a set of query objects and at least one of these must match a document before it is retrieved 

{
    $or:[
        {author:"Daniel"},
        {author:"Jessica"}
    ]
}

This query match all the documents where author is Daniel or Jessica.

To mix AND and OR queries, you just need to use $or as one of regular query fields. 

{
    title:"MongoDB", 
    $or:[
        {author:"Daniel"}, 
        {author:"Jessica"}
    ]
}

Conditionals

Conditional operators <, <=, >, >= and != can't be used directly, as the query object format doesn't support it but the same can be achieved with their aliases $lt, $lte, $gt, $gte and $ne. When a field value needs to match a conditional, the value must be wrapped into a separate object. 

{"fieldname":{$gte:100}}

This query defines that fieldname must be greater than or equal to 100.

Conditionals can also be mixed to create ranges. 

{"fieldname": {$lte:10, $gte:100}}

Regular expressions in queries

Queried field values can also be matched with regular expressions 

{author:/^Daniel/}

Специальные операторы в запросах

In addition to OR and conditional there's some more operators:

  • $in - specifies an array of possible matches, {"name":{$in:[1,2,3]}}
  • $nin - specifies an array of unwanted matches
  • $all - array value must match to the condition {"name":{$all:[1,2,3]}}
  • $exists - checks for existence of a field {"name":{$exists:true}}
  • $mod - check for a modulo {"name":{$mod:{3,2}} is the same as "name" % 3 == 2
  • $size - checks the size of an array value {"name": {$size:2}} matches arrays name with 2 elements

Queries inside objects and arrays

If you have a document with nested objects/arrays then the keys inside these nested objects can still be used for queries.

For example with the following document 

{
    "_id": idvalue,
    "author":{
        "firstname":"Daniel",
        "lastname": "Defoe"
    },
    "books":[
        {
            "title":"Robinson Crusoe"
            "year": 1714
        }
    ]
}

not only the _id field can be used as a query field - also the firstname and even title can be used. This can be done when using nested field names as strings, concated with periods. 

collection.find({"author.firstname":"Daniel})

Works even inside arrays 

collection.find({"books.year":1714})

Query options

Query options define the behavior of the query. 

var options = {
    "limit": 20,
    "skip": 10,
    "sort": title
}

collection.find({}, options).toArray(...);

Paging

Paging can be achieved with option parameters limit and skip 

{
    "limit": 20,
    "skip" 10
}

retrieves 10 elements starting from 20

Sorting

Sorting can be acieved with option parameter sort which takes an array of sort preferences 

{
    "sort": [['field1','asc'], ['field2','desc']]
}

With single ascending field the array can be replaced with the name of the field. 

{
    "sort": "name"
}

Explain

Option parameter explain turns the query into an explain query.

Cursors

Cursor objects are the results for queries and can be used to fetch individual fields from the database.

nextObject

cursor.nextObject(function(err, doc){}) retrieves the next record from database. If doc is null, then there weren't any more records.

each

cursor.each(function(err, doc){}) retrieves all matching records one by one.

toArray

cursor.toArray(function(err, docs){}) converts the cursor object into an array of all the matching records. Probably the most convenient way to retrieve results but be careful with large datasets as every record is loaded into memory. 

collection.find().toArray(function(err, docs){
    console.log("retrieved records:");
    console.log(docs);
});

rewind

cursor.rewind() resets the internal pointer in the cursor to the beginning.

Counting matches

Counting total number of found matches can be done against cursors with method count. 

cursor.count(callback)

Where

  • callback is the callback function with two parameters - an error object (if an error occured) and the number on matches as an integer.

Example 

cursor.count(function(err, count){
    console.log("Total matches: "+count);
});

Replicasets

Introduction

Replica sets is the asynchronous master/slave replication added to Mongodb that takes care off all the failover and recovery for the member nodes. According to the mongodb documentation a replicaset is

  • Two or more nodes that are copies of each other
  • Automatic assignment of a primary(master) node if none is available
  • Drivers that automatically detect the new master and send writes to it

More information at Replicasets

Driver usage

To create a new replicaset follow the instructions on the mongodb site to setup the config and the replicaset instances. Then using the driver. 

var replSet = new ReplSetServers( [ 
    new Server( 127.0.0.1, 30000, { auto_reconnect: true } ),
    new Server( 127.0.0.1, 30001, { auto_reconnect: true } ),
    new Server( 127.0.0.1, 30002, { auto_reconnect: true } )
  ], 
  {rs_name:RS.name}
);

var db = new Db('integration_test_', replSet);
db.open(function(err, p_db) {
  // Do you app stuff :)
})

The ReplSetSrvers object has the following parameters 

var replSet = new ReplSetSrvers(servers, options)

Where

  • servers is an array of Server objects
  • options can contain the following options

Replicaset options

Several options can be passed to the Replicaset constructor with options parameter.

  • rs_name is the name of the replicaset you configured when you started the server, you can have multiple replicasets running on your servers.
  • read_secondary set's the driver to read from secondary servers (slaves) instead of only from the primary(master) server.
  • socketOptions - a collection of pr socket settings

Socket options

Several options can be set for the socketOptions.

  • timeout = set seconds before connection times out default:0
  • noDelay = Disables the Nagle algorithm default:true
  • keepAlive = Set if keepAlive is used default:0, which means no keepAlive, set higher than 0 for keepAlive
  • encoding = 'ascii'|'utf8'|'base64' default:null

Indexes

Indexes are needed to make queries faster. For example if you need to find records by a field named username and the field has a related index set, then the query will be a lot faster compared to if the index was not present.

See MongoDB documentation for details.

Create indexes with createIndex()

createIndex adds a new index to a collection. For checking if the index was already set, use ensureIndex instead. 

collection.createIndex(index[, options], callback)

or 

db.createIndex(collectionname, index[, options], callback)

where

  • index is the field or fields to be indexed. See index field
  • options are options, for example {sparse: true} to include only records that have indexed field set or {unique: true} for unique indexes. If the options is a boolean value, then it indicates if it's an unique index or not.
  • callback gets two parameters - an error object (if an error occured) and the name for the newly created index

Ensure indexes with ensureIndex()

Same as createIndex with the difference that the index is checked for existence before adding to avoid duplicate indexes.

Index field

Index field can be a simple string like "username" to index certain field (in this case, a field named as username). 

collection.ensureIndex("username",callback)

It is possible to index fields inside nested objects, for example "user.firstname" to index field named firstname inside a document named user. 

collection.ensureIndex("user.firstname",callback)

It is also possible to create mixed indexes to include several fields at once. 

collection.ensureIndex({firstname:1, lastname:1}, callback)

or with tuples 

collection.ensureIndex([["firstname", 1], ["lastname", 1]], callback)

The number value indicates direction - if it's 1, then it is an ascending value, if it's -1 then it's descending. For example if you have documents with a field date and you want to sort these records in descending order then you might want to add corresponding index 

collection.ensureIndex({date:-1}, callback)

Remove indexes with dropIndex()

All indexes can be dropped at once with dropIndexes 

collection.dropIndexes(callback)

callback gets two parameters - an error object (if an error occured) and a boolean value true if operation succeeded.

Get index information with indexInformation()

indexInformation can be used to fetch some useful information about collection indexes. 

collection.indexInformation(callback)

Where callback gets two parameters - an error object (if an error occured) and an index information object.

The keys in the index object are the index names and the values are tuples of included fields.

For example if a collection has two indexes - as a default an ascending index for the _id field and an additonal descending index for"username" field, then the index information object would look like the following 

{
    "_id":[["_id", 1]],
    "username_-1":[["username", -1]]
}


GridStore

GridFS is a scalable MongoDB filesystem for storing and retrieving large files. The default limit for a MongoDB record is 16MB, so to store data that is larger than this limit, GridFS can be used. GridFS shards the data into smaller chunks automatically. See MongoDB documentation for details.

GridStore is a single file inside GridFS that can be managed by the script.

Open GridStore

Opening a GridStore (a single file in GridFS) is a bit similar to opening a database. At first you need to create a GridStore object and then open it. 

var gs = new mongodb.GridStore(db, filename, mode[, options])

Where

  • db is the database object
  • filename is the name of the file in GridFS that needs to be accessed/created
  • mode indicated the operation, can be one of:
    • "r" (Read): Looks for the file information in fs.files collection, or creates a new id for this object.
    • "w" (Write): Erases all chunks if the file already exist.
    • "w+" (Append): Finds the last chunk, and keeps writing after it.
  • options can be used to specify some metadata for the file, for example content_type, metadata and chunk_size

Example: 

var gs = new mongodb.GridStore(db, "test.png", "w", {
    "content_type": "image/png",
    "metadata":{
        "author": "Daniel"
    },
    "chunk_size": 1024*4
});

When GridStore object is created, it needs to be opened. 

gs.open(callback);

callback gets two parameters - and error object (if error occured) and the GridStore object.

Opened GridStore object has a set of useful properties

  • gs.length - length of the file in bytes
  • gs.contentType - the content type for the file
  • gs.uploadDate - when the file was uploaded
  • gs.metadata - metadata that was saved with the file
  • gs.chunkSize - chunk size

Example 

gs.open(function(err, gs){
    console.log("this file was uploaded at "+gs.uploadDate);
});

Writing to GridStore

Writing can be done with write 

gs.write(data, callback)

where data is a Buffer or a string, callback gets two parameters - an error object (if error occured) and result value which indicates if the write was successful or not.

While the GridStore is not closed, every write is appended to the opened GridStore.

Writing a file to GridStore

This function opens the GridStore, streams the contents of the file into GridStore, and closes the GridStore. 

gs.writeFile( file, callback )

where

  • file is a file descriptor, or a string file path
  • callback is a function with two parameters - error object (if error occured) and the GridStore object.

Reading from GridStore

Reading from GridStore can be done with read 

gs.read([size], callback)

where

  • size is the length of the data to be read
  • callback is a callback function with two parameters - error object (if an error occured) and data (binary string)

Streaming from GridStore

You can stream data as it comes from the database using stream 

gs.stream([autoclose=false])

where

  • autoclose If true current GridStore will be closed when EOF and 'close' event will be fired

The function returns read stream based on this GridStore file. It supports the events 'read', 'error', 'close' and 'end'.

Delete a GridStore

GridStore files can be unlinked with unlink 

mongodb.GridStore.unlink(db, name, callback)

Where

  • db is the database object
  • name is either the name of a GridStore object or an array of GridStore object names
  • callback is the callback function

Closing the GridStore

GridStore needs to be closed after usage. This can be done with close 

gs.close(callback)

Check the existance of a GridStore file

Checking if a file exists in GridFS can be done with exist 

mongodb.GridStore.exist(db, filename, callback)

Where

  • db is the database object
  • filename is the name of the file to be checked or a regular expression
  • callback is a callback function with two parameters - an error object (if an error occured) and a boolean value indicating if the file exists or not

Seeking in a GridStore

Seeking can be done with seek 

gs.seek(position);

This function moves the internal pointer to the specified position.

Источник — https://support.qbpro.ru/index.php?title=Документация_для_v_1.2&oldid=576