Specify a Query

On this page

Overview

Literal Values
Comparison
Logical
Element
Evaluation
Array
Bitwise
Additional Information

Overview

In this guide, you can learn how to specify a query to match a subset of documents.

To match a subset of documents, specify a query filter containing your match criteria. Match criteria consist of the fields and values you want present in a document. A query filter contains at least one set of match criteria to determine which documents to include in the resulting set.

In a query filter, you can match fields with literal values or with query operators. Query operators allow you to perform mathematical or logical operations to locate documents within a collection.

Match criteria with literal values use the following format:

filter := bson.D{{"<field>", "<value>"}}

Match criteria with a query operator use the following format:

filter := bson.D{{"<field>", bson.D{{"<operator>", "<value>"}}}}

The following sections use literal values and query operators with the Find() method to match a subset of documents.

Sample Data

The examples in this section use the following Tea struct as a model for documents in the tea collection:

type Tea struct {
	Type   string
	Rating int32
	Vendor []string `bson:"vendor,omitempty" json:"vendor,omitempty"`
}

The omitempty struct tag omits the corresponding field from the inserted document when left empty.

To run the examples in this guide, load the sample data into the tea collection in the db database with the following snippet:

coll := client.Database("db").Collection("tea")
docs := []interface{}{
	Tea{Type: "Masala", Rating: 10, Vendor: []string{"A", "C"}},
	Tea{Type: "English Breakfast", Rating: 6},
	Tea{Type: "Oolong", Rating: 7, Vendor: []string{"C"}},
	Tea{Type: "Assam", Rating: 5},
	Tea{Type: "Earl Grey", Rating: 8, Vendor: []string{"A", "B"}},
}
result, err := coll.InsertMany(context.TODO(), docs)

Tip

Nonexistent Databases and Collections

If the necessary database and collection don't exist when you perform a write operation, the server implicitly creates them.

Each document describes a tea type, its rating, and the vendors that carry that variety. These items correspond to the type, rating, and vendor fields.

Literal Values

Literal value query filters return documents with an exact match to your match criteria.

Tip

If you specify an empty query filter, CRUD operations match all the documents in a collection.

Example

The following example matches documents where the type is "Oolong":

filter := bson.D{{"type", "Oolong"}}
cursor, err := coll.Find(context.TODO(), filter)
if err != nil {
    panic(err)
}
var results []Tea
if err = cursor.All(context.TODO(), &results); err != nil {
    panic(err)
}
for _, result := range results {
    res, _ := bson.MarshalExtJSON(result, false, false)
    fmt.Println(string(res))
}

{"type":"Oolong","rating":7,"vendor":["C"]}

Tip

Literal value queries return the same value as the $eq comparison operator. For example, the following query filters produce the same result:

filter := bson.D{{"type", "Oolong"}}

filter := bson.D{{"type", bson.D{{"$eq", "Oolong"}}}}

Comparison

Comparison operators analyze the value in a document against the specified value in your match criteria. Common comparison operators include $gt for "greater than" comparisons, $lte for "less than or equal to" comparisons, and $ne for "not equal to" comparisons.

Example

The following example matches documents where the rating is less than 7:

filter := bson.D{{"rating", bson.D{{"$lt", 7}}}}
cursor, err := coll.Find(context.TODO(), filter)
if err != nil {
   panic(err)
}
var results []Tea
if err = cursor.All(context.TODO(), &results); err != nil {
    panic(err)
}
for _, result := range results {
    res, _ := bson.MarshalExtJSON(result, false, false)
    fmt.Println(string(res))
}

{"type":"English Breakfast","rating":6}
{"type":"Assam","rating":5}

For a full list of comparison operators, see the Comparison Query Operators page.

Logical

Logical operators require at least two match criteria. They check if documents meet all, at lease one, or none of the specified criteria. Common logical operators include $and where all match criteria must be true, and $or where at least one of the match criteria must be true.

Example

The following example matches documents where the rating is greater than 7 and less than or equal to 10:

filter := bson.D{
   {"$and",
      bson.A{
         bson.D{{"rating", bson.D{{"$gt", 7}}}},
         bson.D{{"rating", bson.D{{"$lte", 10}}}},
      },
   },
}
cursor, err := coll.Find(context.TODO(), filter)
if err != nil {
   panic(err)
}
var results []Tea
if err = cursor.All(context.TODO(), &results); err != nil {
    panic(err)
}
for _, result := range results {
    res, _ := bson.MarshalExtJSON(result, false, false)
    fmt.Println(string(res))
}

{"type":"Masala","rating":10,"vendor":["A","C"]}
{"type":"Earl Grey","rating":8,"vendor":["A","B"]}

For a full list of logical operators, see the Logical Query Operators page.

Tip

Multiple match criteria resembling an $eq comparison operator in a literal query return the same value as the $and logical operator. For example, the following query filters produce the same result:

filter := bson.D{{"type", "Oolong"}, {"rating", 7}}

filter := bson.D{
  {"$and",
    bson.A{
      bson.D{{"type", "Oolong"}},
      bson.D{{"rating", 7}},
    }},
}

Element

Element operators check for the presence or type of the specified field.

Example

The following example matches documents where the vendor field does not exist:

filter := bson.D{{"vendor", bson.D{{"$exists", false}}}}
cursor, err := coll.Find(context.TODO(), filter)
if err != nil {
   panic(err)
}
var results []Tea
if err = cursor.All(context.TODO(), &results); err != nil {
    panic(err)
}
for _, result := range results {
    res, _ := bson.MarshalExtJSON(result, false, false)
    fmt.Println(string(res))
}

{"type":"English Breakfast","rating":6}
{"type":"Assam","rating":5}

For a full list of element operators, see the Element Query Operators page.

Evaluation

Evaluation operators analyze values in a document based on the specified value in your match criteria. Common evaluation operators include $regex where a field's value must match the specified regular expression and $text where the field's value must contain the specified string.

Example

The following example matches documents where the type begins with the letter "E":

filter := bson.D{{"type", bson.D{{"$regex", "^E"}}}}
cursor, err := coll.Find(context.TODO(), filter)
if err != nil {
   panic(err)
}
var results []Tea
if err = cursor.All(context.TODO(), &results); err != nil {
    panic(err)
}
for _, result := range results {
    res, _ := bson.MarshalExtJSON(result, false, false)
    fmt.Println(string(res))
}

{"type":"English Breakfast","rating":6}
{"type":"Earl Grey","rating":8,"vendor":["A","B"]}

For a full list of evaluation operators, see the Evaluation Query Operators page.

Array

Array operators check the values or amount of elements in an array field.

Example

The following example matches documents where the vendor contains "C":

filter := bson.D{{"vendor", bson.D{{"$all", bson.A{"C"}}}}}
cursor, err := coll.Find(context.TODO(), filter)
if err != nil {
   panic(err)
}
var results []Tea
if err = cursor.All(context.TODO(), &results); err != nil {
    panic(err)
}
for _, result := range results {
    res, _ := bson.MarshalExtJSON(result, false, false)
    fmt.Println(string(res))
}

{"type":"Masala","rating":10,"vendor":["A","C"]}
{"type":"Oolong","rating":7,"vendor":["C"]}

For a full list of array operators, see the Array Query Operators page.

Bitwise

Bitwise operators convert a numeric field from a base-10 (decimal) number into the corresponding base-2 (binary) number. They check whether the value in a document has the same bits set as the value in your match criteria.

Example

The following example matches documents where the rating has the same bits set as 6 (which is "00000110"):

filter := bson.D{{"rating", bson.D{{"$bitsAllSet", 6}}}}
cursor, err := coll.Find(context.TODO(), filter)
if err != nil {
   panic(err)
}
var results []Tea
if err = cursor.All(context.TODO(), &results); err != nil {
    panic(err)
}
for _, result := range results {
    res, _ := bson.MarshalExtJSON(result, false, false)
    fmt.Println(string(res))
}

{"type":"English Breakfast","rating":6}
{"type":"Oolong","rating":7,"vendor":["C"]}

For a full list of bitwise operators, see the Bitwise Query Operators page.

Additional Information

For information on specifying a geospatial query, see the guide on Geospatial Data.

API Documentation

To learn more about any of the methods or types used in this guide, see the following API Documentation:

Back

Read Operations

Count Documents