Specify a Query

Specify a Query
- Specify a Query
- Overview
  - Sample Data
- Literal Values
  - Example
- Comparison
  - Example
- Logical
  - Example
- Element
  - Example
- Evaluation
  - Example
- Array
  - Example
- Bitwise
  - Example
- Additional Information
  - API Documentation

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Specify a Query

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](https://www.mongodb.com/docs/drivers/go/current/crud/query/query-document.md#std-label-golang-literal-values or with [query operators](https://www.mongodb.com/docs/drivers/go/current/crud/query/query-document.md#std-label-golang-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](https://www.mongodb.com/docs/drivers/go/current/crud/query/query-document.md#std-label-golang-literal-values and [query operators](https://www.mongodb.com/docs/drivers/go/current/crud/query/query-document.md#std-label-golang-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](https://www.mongodb.com/docs/drivers/go/current/data-formats/bson.md#std-label-golang-struct-tags 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 := []any{
    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))
}

Output:

{"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))
}

Output:

{"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))
}

Output:

{"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))
}

Output:

{"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))
}

Output:

{"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))
}

Output:

{"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))
}

Output:

{"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.](https://www.mongodb.com/docs/drivers/go/current/data-formats/geo.md#std-label-golang-geo

API Documentation

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

[Find()](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/mongo#Collection.Find
[Cursor](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/mongo#Cursor

Local MCP Server Configuration

Specify a Query

Specify a Query

Overview

Sample Data

Literal Values

Example

Comparison

Example

Logical

Example

Element

Example

Evaluation

Example

Array

Example

Bitwise

Example

Additional Information

API Documentation