Especificar uma query
Nesta página
Visão geral
Neste guia, você pode aprender como especificar uma query para corresponder a um subconjunto de documentos.
Para corresponder a um subconjunto de documentos, especifique um filtro de query contendo seus critérios de correspondência. Os critérios de correspondência consistem nos campos e valores que você deseja apresentar em um documento. Um filtro de consulta contém pelo menos um conjunto de critérios de correspondência para determinar quais documentos incluir no conjunto resultante.
Em um filtro de queries, você pode corresponder campos com valores literais ou com operadores de query. Os operadores de query permitem que você realize operações matemáticas ou lógicas para localizar documentos dentro de uma coleção.
Os critérios de correspondência com valores literais usam o seguinte formato:
filter := bson.D{{"<field>", "<value>"}}
Os critérios de correspondência com um operador de query usam o seguinte formato:
filter := bson.D{{"<field>", bson.D{{"<operator>", "<value>"}}}}
As seções a seguir usam valores literais e operadores de query com o método Find()
para corresponder a um subconjunto de documentos.
Dados de amostra
Os exemplos nesta seção usam o seguinte struct Tea
como um modelo para documentos na coleção tea
:
type Tea struct { Type string Rating int32 Vendor []string `bson:"vendor,omitempty" json:"vendor,omitempty"` }
A tag struct omitempty
omite o campo correspondente do documento inserido quando deixado vazio.
Para executar os exemplos neste guia, carregue os dados de amostra na collection do tea
no banco de dados do db
com o seguinte trecho:
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)
Dica
Bancos de Dados e Coleções Inexistentes
Se o banco de dados e a collection necessários não existirem quando você executar uma operação de escrita, o servidor implicitamente os criará.
Cada documento descreve um tipo de chá, sua classificação e os fornecedores que carregam essa variedade. Estes itens correspondem aos campos type
, rating
e vendor
.
Valores literais
Os filtros de query de valor literal retornam documentos com uma correspondência exata em relação a seus critérios de correspondência.
Dica
Se você especificar um filtro de query vazio, as operações CRUD corresponderão a todos os documentos em uma collection.
Exemplo
O exemplo a seguir corresponde aos documentos em que o type
é "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)) }
Dica
Queries de valor literal retornam o mesmo valor que o operador de comparação $eq
. Por exemplo, os seguintes filtros de query produzem o mesmo resultado:
filter := bson.D{{"type", "Oolong"}}
filter := bson.D{{"type", bson.D{{"$eq", "Oolong"}}}}
Comparação
Os operadores de comparação analisam o valor em um documento em relação ao valor especificado nos seus critérios de correspondência. Os operadores de comparação comuns incluem $gt
para comparações "maior que", $lte
para comparações "menor que ou igual a" e $ne
para comparações "não igual a".
Exemplo
O exemplo a seguir corresponde a documentos em que rating
é menor que 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)) }
Para uma lista completa de operadores de comparação, consulte a página Operadores de query de comparação .
Lógica
Os operadores lógicos exigem pelo menos dois critérios de correspondência. Eles verificam se os documentos atendem a todos, pelo menos um ou nenhum dos critérios especificados. Os operadores lógicos comuns incluem $and
, em que todos os critérios de correspondência devem ser verdadeiros, e $or
, em que pelo menos um dos critérios de correspondência deve ser verdadeiro.
Exemplo
O exemplo a seguir corresponde a documentos onde o rating
é maior que 7
e menor ou igual a 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)) }
Para uma lista completa dos operadores lógicos, consulte a página Operadores lógicos de query.
Dica
Os critérios de correspondência múltipla semelhantes a um operador de comparação $eq
em uma consulta literal retornam o mesmo valor que o operador lógico $and
. Por exemplo, os seguintes filtros de query produzem o mesmo resultado:
filter := bson.D{{"type", "Oolong"}, {"rating", 7}}
filter := bson.D{ {"$and", bson.A{ bson.D{{"type", "Oolong"}}, bson.D{{"rating", 7}}, }}, }
Elemento
Os operadores de elemento verificam a presença ou tipo do campo especificado.
Exemplo
O exemplo a seguir corresponde a documentos onde o campo vendor
não existe:
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)) }
Para uma lista completa dos operadores de elementos, consulte a página Operadores de query de elementos.
Avaliação
Os operadores de avaliação analisam valores em um documento com base no valor especificado em seus critérios de correspondência. Os operadores de avaliação comuns incluem $regex
onde o valor de um campo deve corresponder à expressão regular especificada e $text
onde o valor do campo deve conter a string especificada.
Exemplo
O exemplo a seguir corresponde a documentos em que o type
começa com a letra "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)) }
Para uma lista completa dos operadores de avaliação, consulte a página Operadores de query de avaliação.
Array
Os operadores de array verificam os valores ou a quantidade de elementos em um campo de array.
Exemplo
O exemplo a seguir corresponde aos documentos onde o vendor
contém "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)) }
Para uma lista completa de operadores de array, consulte a página Operadores de query de array .
Bitwise
Os operadores bit a bit convertem um campo numérico de um número de base 10 (decimal) no número de base 2 (binário) correspondente. Eles verificam se o valor em um documento tem os mesmos bits definidos como o valor em seus critérios de correspondência.
Exemplo
O exemplo a seguir corresponde a documentos em que a rating
tem os mesmos bits definidos como 6
(que é "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)) }
Para uma lista completa de operadores bitwise, consulte a página Operadores de query bitwise.
Informações adicionais
Para obter informações sobre como especificar uma query geospacial, consulte o guia sobre dados geoespaciais.
Documentação da API
Para saber mais sobre qualquer um dos métodos ou tipos usados neste guia, consulte a seguinte documentação da API: