Docs Menu

Docs HomeGo

Specify a Query

On this page

  • Overview
  • Literal Values
  • Comparison
  • Logical
  • Element
  • Evaluation
  • Array
  • Bitwise
  • Additional Information

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.

The examples in this section use the following Tea struct as a model for documents in the ratings 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.ratings collection with the following snippet:

coll := client.Database("tea").Collection("ratings")
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

Non-existent 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 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.

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, _ := json.Marshal(result)
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 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.

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, _ := json.Marshal(result)
fmt.Println(string(res))
}

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

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.

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, _ := json.Marshal(result)
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 operators check for the presence or type of the specified field.

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, _ := json.Marshal(result)
fmt.Println(string(res))
}

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

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.

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, _ := json.Marshal(result)
fmt.Println(string(res))
}

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

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

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, _ := json.Marshal(result)
fmt.Println(string(res))
}

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

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.

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, _ := json.Marshal(result)
fmt.Println(string(res))
}

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

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

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

←  Read OperationsCount Documents →