Specify a Query
On this page
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)) }
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)) }
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)) }
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)) }
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)) }
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)) }
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)) }
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: