<commit_before>Main Documentation site
=======================

[Documentation](http://mongodb.github.com/node-mongodb-native/)

Install
========

To install the most recent release from npm, run:

    npm install mongodb
    
That may give you a warning telling you that bugs['web'] should be bugs['url'], it would be safe to ignore it (this has been fixed in the development version) 

To install the latest from the repository, run::

    npm install path/to/node-mongodb-native

Community
========
Check out the google group [node-mongodb-native](http://groups.google.com/group/node-mongodb-native) for questions/answers from users of the driver.

Introduction
========

This is a node.js driver for MongoDB. It's a port (or close to a port) of the library for ruby at http://github.com/mongodb/mongo-ruby-driver/.

A simple example of inserting a document.

    var client = new Db('test', new Server("127.0.0.1", 27017, {})),
        test = function (err, collection) {
          collection.insert({a:2}, function(err, docs) {

            collection.count(function(err, count) {
              test.assertEquals(1, count);
            });

            // Locate all the entries using find
            collection.find().toArray(function(err, results) {
              test.assertEquals(1, results.length);
              test.assertTrue(results[0].a === 2);

              // Let's close the db
              client.close();
            });
          });
        };

    client.open(function(err, p_client) {
      client.collection('test_insert', test);
    });

Data types
========

To store and retrieve the non-JSON MongoDb primitives ([ObjectID](http://www.mongodb.org/display/DOCS/Object+IDs), Long, Binary, [Timestamp](http://www.mongodb.org/display/DOCS/Timestamp+data+type), [DBRef](http://www.mongodb.org/display/DOCS/Database+References#DatabaseReferences-DBRef), Code).

In particular, every document has a unique `_id` which can be almost any type, and by default a 12-byte ObjectID is created. ObjectIDs can be represented as 24-digit hexadecimal strings, but you must convert the string back into an ObjectID before you can use it in the database. For example: 

    // Get the objectID type
    var ObjectID = require('mongodb').ObjectID;
    
    var idString = '4e4e1638c85e808431000003';
    collection.findOne({_id: new ObjectID(idString)}, console.log)  // ok
    collection.findOne({_id: idString}, console.log)  // wrong! callback gets undefined

Here are the constructors the non-Javascript BSON primitive types:

    // Fetch the library
    var mongo = require('mongodb');
    // Create new instances of BSON types
    new mongo.Long(numberString)
    new mongo.ObjectID(hexString)
    new mongo.Timestamp()  // the actual unique number is generated on insert.
    new mongo.DBRef(collectionName, id, dbName)
    new mongo.Binary(buffer)  // takes a string or Buffer
    new mongo.Code(code, [context])
    new mongo.Symbol(string)
    new mongo.MinKey()
    new mongo.MaxKey()
    new mongo.Double(number)	// Force double storage

The C/C++ bson parser/serializer
--------

From V0.8.0 to V0.9.6.9, the Javascript bson parser was slower than an optional C/C++ bson parser. As of V0.9.6.9+, due to performance improvements in the Javascript parser, the C/C++ parser is deprecated and is not installed by default anymore.

If you are running a version of this library has the C/C++ parser compiled, to enable the driver to use the C/C++ bson parser pass it the option native_parser:true like below

    // using Deprecated native_parser:
    var client = new Db('integration_tests_20',
                        new Server("127.0.0.1", 27017),
                        {native_parser:true});

The C++ parser uses the js objects both for serialization and deserialization.

GitHub information
========

The source code is available at http://github.com/christkv/node-mongodb-native.
You can either clone the repository or download a tarball of the latest release.

Once you have the source you can test the driver by running

    $ make test

in the main directory. You will need to have a mongo instance running on localhost for the integration tests to pass.

Examples
========

For examples look in the examples/ directory. You can execute the examples using node.

    $ cd examples
    $ node queries.js

GridStore
=========

The GridStore class allows for storage of binary files in mongoDB using the mongoDB defined files and chunks collection definition.

For more information have a look at [Gridstore](https://github.com/christkv/node-mongodb-native/blob/master/docs/gridfs.md)

Replicasets
===========
For more information about how to connect to a replicaset have a look at [Replicasets](https://github.com/christkv/node-mongodb-native/blob/master/docs/replicaset.md)

Primary Key Factories
--------

Defining your own primary key factory allows you to generate your own series of id's
(this could f.ex be to use something like ISBN numbers). The generated the id needs to be a 12 byte long "string".

Simple example below

    // Custom factory (need to provide a 12 byte array);
    CustomPKFactory = function() {}
    CustomPKFactory.prototype = new Object();
    CustomPKFactory.createPk = function() {
      return new ObjectID("aaaaaaaaaaaa");
    }

    var p_client = new Db('integration_tests_20', new Server("127.0.0.1", 27017, {}), {'pk':CustomPKFactory});
    p_client.open(function(err, p_client) {
      p_client.dropDatabase(function(err, done) {
        p_client.createCollection('test_custom_key', function(err, collection) {
          collection.insert({'a':1}, function(err, docs) {
            collection.find({'_id':new ObjectID("aaaaaaaaaaaa")}, function(err, cursor) {
              cursor.toArray(function(err, items) {
                test.assertEquals(1, items.length);

                // Let's close the db
                p_client.close();
              });
            });
          });
        });
      });
    });

Strict mode
--------

Each database has an optional strict mode. If it is set then asking for a collection
that does not exist will return an Error object in the callback. Similarly if you
attempt to create a collection that already exists. Strict is provided for convenience.

    var error_client = new Db('integration_tests_', new Server("127.0.0.1", 27017, {auto_reconnect: false}), {strict:true});    
      test.assertEquals(true, error_client.strict);
      
      error_client.open(function(err, error_client) {
      error_client.collection('does-not-exist', function(err, collection) {
        test.assertTrue(err instanceof Error);
        test.assertEquals("Collection does-not-exist does not exist. Currently in strict mode.", err.message);
      });

      error_client.createCollection('test_strict_access_collection', function(err, collection) {
        error_client.collection('test_strict_access_collection', function(err, collection) {
          test.assertTrue(collection instanceof Collection);
          // Let's close the db
          error_client.close();
        });
      });
    });

Documentation
========

If this document doesn't answer your questions, see the source of
[Collection](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/collection.js)
or [Cursor](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/cursor.js),
or the documentation at MongoDB for query and update formats.

Find
--------

The find method is actually a factory method to create
Cursor objects. A Cursor lazily uses the connection the first time
you call `nextObject`, `each`, or `toArray`.

The basic operation on a cursor is the `nextObject` method
that fetches the next matching document from the database. The convenience
methods `each` and `toArray` call `nextObject` until the cursor is exhausted.

Signatures:
<commit_msg>fixed urls to new repo<commit_after>Main Documentation site
=======================

[Documentation](http://mongodb.github.com/node-mongodb-native/)

Install
========

To install the most recent release from npm, run:

    npm install mongodb
    
That may give you a warning telling you that bugs['web'] should be bugs['url'], it would be safe to ignore it (this has been fixed in the development version) 

To install the latest from the repository, run::

    npm install path/to/node-mongodb-native

Community
========
Check out the google group [node-mongodb-native](http://groups.google.com/group/node-mongodb-native) for questions/answers from users of the driver.

Introduction
========

This is a node.js driver for MongoDB. It's a port (or close to a port) of the library for ruby at http://github.com/mongodb/mongo-ruby-driver/.

A simple example of inserting a document.

    var client = new Db('test', new Server("127.0.0.1", 27017, {})),
        test = function (err, collection) {
          collection.insert({a:2}, function(err, docs) {

            collection.count(function(err, count) {
              test.assertEquals(1, count);
            });

            // Locate all the entries using find
            collection.find().toArray(function(err, results) {
              test.assertEquals(1, results.length);
              test.assertTrue(results[0].a === 2);

              // Let's close the db
              client.close();
            });
          });
        };

    client.open(function(err, p_client) {
      client.collection('test_insert', test);
    });

Data types
========

To store and retrieve the non-JSON MongoDb primitives ([ObjectID](http://www.mongodb.org/display/DOCS/Object+IDs), Long, Binary, [Timestamp](http://www.mongodb.org/display/DOCS/Timestamp+data+type), [DBRef](http://www.mongodb.org/display/DOCS/Database+References#DatabaseReferences-DBRef), Code).

In particular, every document has a unique `_id` which can be almost any type, and by default a 12-byte ObjectID is created. ObjectIDs can be represented as 24-digit hexadecimal strings, but you must convert the string back into an ObjectID before you can use it in the database. For example: 

    // Get the objectID type
    var ObjectID = require('mongodb').ObjectID;
    
    var idString = '4e4e1638c85e808431000003';
    collection.findOne({_id: new ObjectID(idString)}, console.log)  // ok
    collection.findOne({_id: idString}, console.log)  // wrong! callback gets undefined

Here are the constructors the non-Javascript BSON primitive types:

    // Fetch the library
    var mongo = require('mongodb');
    // Create new instances of BSON types
    new mongo.Long(numberString)
    new mongo.ObjectID(hexString)
    new mongo.Timestamp()  // the actual unique number is generated on insert.
    new mongo.DBRef(collectionName, id, dbName)
    new mongo.Binary(buffer)  // takes a string or Buffer
    new mongo.Code(code, [context])
    new mongo.Symbol(string)
    new mongo.MinKey()
    new mongo.MaxKey()
    new mongo.Double(number)	// Force double storage

The C/C++ bson parser/serializer
--------

From V0.8.0 to V0.9.6.9, the Javascript bson parser was slower than an optional C/C++ bson parser. As of V0.9.6.9+, due to performance improvements in the Javascript parser, the C/C++ parser is deprecated and is not installed by default anymore.

If you are running a version of this library has the C/C++ parser compiled, to enable the driver to use the C/C++ bson parser pass it the option native_parser:true like below

    // using Deprecated native_parser:
    var client = new Db('integration_tests_20',
                        new Server("127.0.0.1", 27017),
                        {native_parser:true});

The C++ parser uses the js objects both for serialization and deserialization.

GitHub information
========

The source code is available at http://github.com/mongodb/node-mongodb-native.
You can either clone the repository or download a tarball of the latest release.

Once you have the source you can test the driver by running

    $ make test

in the main directory. You will need to have a mongo instance running on localhost for the integration tests to pass.

Examples
========

For examples look in the examples/ directory. You can execute the examples using node.

    $ cd examples
    $ node queries.js

GridStore
=========

The GridStore class allows for storage of binary files in mongoDB using the mongoDB defined files and chunks collection definition.

For more information have a look at [Gridstore](https://github.com/mongodb/node-mongodb-native/blob/master/docs/gridfs.md)

Replicasets
===========
For more information about how to connect to a replicaset have a look at [Replicasets](https://github.com/mongodb/node-mongodb-native/blob/master/docs/replicaset.md)

Primary Key Factories
--------

Defining your own primary key factory allows you to generate your own series of id's
(this could f.ex be to use something like ISBN numbers). The generated the id needs to be a 12 byte long "string".

Simple example below

    // Custom factory (need to provide a 12 byte array);
    CustomPKFactory = function() {}
    CustomPKFactory.prototype = new Object();
    CustomPKFactory.createPk = function() {
      return new ObjectID("aaaaaaaaaaaa");
    }

    var p_client = new Db('integration_tests_20', new Server("127.0.0.1", 27017, {}), {'pk':CustomPKFactory});
    p_client.open(function(err, p_client) {
      p_client.dropDatabase(function(err, done) {
        p_client.createCollection('test_custom_key', function(err, collection) {
          collection.insert({'a':1}, function(err, docs) {
            collection.find({'_id':new ObjectID("aaaaaaaaaaaa")}, function(err, cursor) {
              cursor.toArray(function(err, items) {
                test.assertEquals(1, items.length);

                // Let's close the db
                p_client.close();
              });
            });
          });
        });
      });
    });

Strict mode
--------

Each database has an optional strict mode. If it is set then asking for a collection
that does not exist will return an Error object in the callback. Similarly if you
attempt to create a collection that already exists. Strict is provided for convenience.

    var error_client = new Db('integration_tests_', new Server("127.0.0.1", 27017, {auto_reconnect: false}), {strict:true});    
      test.assertEquals(true, error_client.strict);
      
      error_client.open(function(err, error_client) {
      error_client.collection('does-not-exist', function(err, collection) {
        test.assertTrue(err instanceof Error);
        test.assertEquals("Collection does-not-exist does not exist. Currently in strict mode.", err.message);
      });

      error_client.createCollection('test_strict_access_collection', function(err, collection) {
        error_client.collection('test_strict_access_collection', function(err, collection) {
          test.assertTrue(collection instanceof Collection);
          // Let's close the db
          error_client.close();
        });
      });
    });

Documentation
========

If this document doesn't answer your questions, see the source of
[Collection](https://github.com/mongodb/node-mongodb-native/blob/master/lib/mongodb/collection.js)
or [Cursor](https://github.com/mongodb/node-mongodb-native/blob/master/lib/mongodb/cursor.js),
or the documentation at MongoDB for query and update formats.

Find
--------

The find method is actually a factory method to create
Cursor objects. A Cursor lazily uses the connection the first time
you call `nextObject`, `each`, or `toArray`.

The basic operation on a cursor is the `nextObject` method
that fetches the next matching document from the database. The convenience
methods `each` and `toArray` call `nextObject` until the cursor is exhausted.

Signatures:

{'fraction_non_alphanumeric': 0.11174675819984745, 'fraction_numerical': 0.011950165268243072, 'mean_word_length': 3.2556126589126317, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 12, 'substrings_counts': 4, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4453540', 'n_tokens_mistral': 4526, 'n_tokens_neox': 4253, 'n_words': 1554}