.\" This manpage is Copyright (C) 2016 MongoDB, Inc.
.\" 
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.3
.\" or any later version published by the Free Software Foundation;
.\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the section entitled "GNU
.\" Free Documentation License".
.\" 
.TH "CLIENT_SIDE_DOCUMENT_MATCHING" "3" "2016\(hy10\(hy12" "MongoDB C Driver"
.SH NAME
Client_Side_Document_Matching \- None
.SH "BASIC DOCUMENT MATCHING (DEPRECATED)"


.B NOTE
.RS
This feature will be removed in version 2.0.
.RE

The MongoDB C driver supports matching a subset of the MongoDB query specification on the client.

Currently, basic numeric, string, subdocument, and array equality,
.B $gt
,
.B $gte
,
.B $lt
,
.B $lte
,
.B $in
,
.B $nin
,
.B $ne
,
.B $exists
,
.B $type
,
.B $and
, and
.B $or
are supported. As this is not the same implementation as the MongoDB server, some inconsistencies may occur. Please file a bug if you find such a case.

The following example performs a basic query against a BSON document.

.SH "EXAMPLE-MATCHER.C"

.nf

#include <bcon.h>
#include <mongoc.h>
#include <stdio.h>

static void
log_query (const bson_t *doc,
           const bson_t *query)
{
   char *str1;
   char *str2;

   str1 = bson_as_json (doc, NULL);
   str2 = bson_as_json (query, NULL);

   printf ("Matching %s against %s\en", str2, str1);

   bson_free (str1);
   bson_free (str2);
}

static void
check_match (const bson_t *doc,
             const bson_t *query)
{
   bson_error_t error;
   mongoc_matcher_t *matcher = mongoc_matcher_new (query, &error);
   if (!matcher) {
      fprintf (stderr, "Error: %s\en", error.message);
      return;
   }

   if (mongoc_matcher_match (matcher, doc)) {
      printf ("  Document matched!\en");
   } else {
      printf ("  No match.\en");
   }

   mongoc_matcher_destroy (matcher);
}

static void
example (void)
{
   bson_t *query;
   bson_t *doc;

   doc = BCON_NEW ("hello", "[", "{", "foo", BCON_UTF8 ("bar"), "}", "]");
   query = BCON_NEW ("hello.0.foo", BCON_UTF8 ("bar"));

   log_query (doc, query);
   check_match (doc, query);

   bson_destroy (doc);
   bson_destroy (query);

   /* i is > 1 or i < \(hy1. */
   query = BCON_NEW ("$or", "[",
                     "{", "i", "{", "$gt", BCON_INT32 (1), "}", "}",
                     "{", "i", "{", "$lt", BCON_INT32 (\(hy1), "}", "}", "]");

   doc = BCON_NEW ("i", BCON_INT32 (2));
   log_query (doc, query);
   check_match (doc, query);

   bson_destroy (doc);

   doc = BCON_NEW ("i", BCON_INT32 (0));
   log_query (doc, query);
   check_match (doc, query);

   bson_destroy (doc);
   bson_destroy (query);
}

int
main (int argc,
      char *argv[])
{
   mongoc_init ();
   example ();
   mongoc_cleanup ();

   return 0;
}
.fi


The following example shows how to process a BSON stream from
.B stdin
and match it against a query. This can be useful if you need to perform simple matching against
.B mongodump
backups.

.SH "FILTER-BSONDUMP.C"

.nf

/*
 * Copyright 2014 MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE\(hy2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


#include <bcon.h>
#include <bson.h>
#include <mongoc.h>
#include <stdio.h>


/*
 * This is an example that reads BSON documents from STDIN and prints them
 * to standard output as JSON if they match {'hello': 'world'}.
 */


int
main (int   argc,
      char *argv[])
{
   mongoc_matcher_t *matcher;
   bson_reader_t *reader;
   const bson_t *bson;
   bson_t *spec;
   char *str;
   int fd;

   mongoc_init ();

#ifdef _WIN32
   fd = fileno (stdin);
#else
   fd = STDIN_FILENO;
#endif

   reader = bson_reader_new_from_fd (fd, false);

   spec = BCON_NEW ("hello", "world");
   matcher = mongoc_matcher_new (spec, NULL);

   while ((bson = bson_reader_read (reader, NULL))) {
      if (mongoc_matcher_match (matcher, bson)) {
         str = bson_as_json (bson, NULL);
         printf ("%s\en", str);
         bson_free (str);
      }
   }

   bson_reader_destroy (reader);
   bson_destroy (spec);

   return 0;
}
.fi


To test this, perform a
.B mongodump
of a single collection and pipe it to the program.

.B $ 
.B echo "db.test.insert({hello:'world'})" | mongo
.nf
MongoDB shell version: 2.6.1
connecting to: test
WriteResult({ "nInserted" : 1 })
bye
.fi
.B $ 
.B mongodump -d test -c test -o - | filter-bsondump
.nf
{ "_id" : { "$oid" : "537afac9a70e5b4d556153bc" }, "hello" : "world" }
.fi


.B
.SH COLOPHON
This page is part of MongoDB C Driver.
Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.