Retrieve Data

Nesta página

Visão geral
Dados de amostra
Encontrar operações
Localizar todos os documentos
Encontrar um documento
Modificar comportamento
Operações de agregação
Agregação
Modificar comportamento
Informações adicionais
Documentação da API

Visão geral

Neste guia, você pode aprender como recuperar dados de suas coleções MongoDB usando operações de leitura.

As operações de leitura permitem que fazer o seguinte:

Recupere documentos de suas coleções usando operações de localização
Realize transformações em documentos em suas coleções usando operações de agregação

Dados de amostra

Os exemplos deste guia utilizam o seguinte Tea estruturado como um modelo para documentos na coleção tea:

type Tea struct {
	Item        string    `bson:"item,omitempty"`
	Rating      int32     `bson:"rating,omitempty"`
	DateOrdered time.Time `bson:"date_ordered,omitempty"`
}

Para executar os exemplos neste guia, carregue estes documentos na coleção tea no banco de dados do db utilizando o seguinte trecho:

coll := client.Database("db").Collection("tea")
docs := []interface{}{
	Tea{Item: "Masala", Rating: 10, DateOrdered: time.Date(2009, 11, 17, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Sencha", Rating: 7, DateOrdered: time.Date(2009, 11, 18, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Masala", Rating: 9, DateOrdered: time.Date(2009, 11, 12, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Masala", Rating: 8, DateOrdered: time.Date(2009, 12, 1, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Sencha", Rating: 10, DateOrdered: time.Date(2009, 12, 17, 0, 0, 0, 0, time.Local)},
	Tea{Item: "Hibiscus", Rating: 4, DateOrdered: time.Date(2009, 12, 18, 0, 0, 0, 0, time.Local)},
}
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 a variedade de chá que um cliente pediu, sua classificação e a data do pedido. Estas descrições correspondem aos campos item, rating e date_ordered.

Encontrar operações

Use localizar operações para recuperar dados do MongoDB. As operações de localização consistem nos métodos Find() e FindOne().

Localizar todos os documentos

O método Find() espera que você passe um tipo Context e um filtro de query. O método retorna todos os documentos que correspondem ao filtro como um tipo Cursor.

Para um exemplo que utiliza o método Find(), consulte a seção Encontrar Exemplo desta página. Para saber como acessar dados usando um cursor, consulte o guia Acessar dados de um cursor.

Encontrar um documento

O método FindOne() espera que você passe um tipo de Context e um filtro de query. O método retorna o primeiro documento que corresponde ao filtro como um tipo SingleResult.

Para ver um exemplo que usa o método FindOne(), consulte a seção Encontrar um exemplo nesta página. Para ver um exemplo que usa FindOne() e faz queries usando um valor de ObjectId específico, consulte a seção Exemplo de localizar um por ObjectId nesta página.

Para saber como acessar dados de um tipo SingleResult, consulte Unmarshalling no guia BSON.

Modificar comportamento

Você pode modificar o comportamento de Find() e FindOne() passando os tipos FindOptions e FindOneOptions, respectivamente. Se você não especificar nenhuma opção, o driver usará os valores padrão para cada opção.

Você pode configurar as opções normalmente usadas em ambos os tipos com os seguintes métodos:

Método	Descrição
`SetCollation()`	The type of language collation to use when sorting results. Default: `nil`
`SetLimit()`	The maximum number of documents to return. Default: `0` This option is not available for `FindOneOptions`. The `FindOne()` method internally uses `SetLimit(-1)`.
`SetProjection()`	The fields to include in the returned documents. Default: `nil`
`SetSkip()`	The number of documents to skip. Default: `0`
`SetSort()`	The field and type of sort to order the matched documents. You can specify an ascending or descending sort. Default: none

Exemplo de localização

O exemplo seguinte passa um contexto, filtro e FindOptions para o método Find(), que executa as seguintes ações:

Corresponde aos documentos onde o valor de rating está entre 5 e 9 (exclusivo)
Classifica os documentos correspondentes em ordem crescente por date_ordered

filter := bson.D{
	{"$and",
		bson.A{
			bson.D{{"rating", bson.D{{"$gt", 5}}}},
			bson.D{{"rating", bson.D{{"$lt", 9}}}},
		}},
}
sort := bson.D{{"date_ordered", 1}}
opts := options.Find().SetSort(sort)
// Retrieves documents that match the filter and prints them as structs
cursor, err := coll.Find(context.TODO(), filter, opts)
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))
}

{"item":"Sencha","rating":7,"date_ordered":"2009-11-18T05:00:00Z"}
{"item":"Masala","rating":8,"date_ordered":"2009-12-01T05:00:00Z"}

Encontrar um exemplo

O exemplo seguinte passa um contexto, filtro e FindOneOptions para o método FindOne(), que executa as seguintes ações:

Corresponde a documentos onde o valor date_ordered é igual ou anterior a 30 de novembro de 2009
Ignora os dois primeiros documentos correspondentes

filter := bson.D{{"date_ordered", bson.D{{"$lte", time.Date(2009, 11, 30, 0, 0, 0, 0, time.Local)}}}}
opts := options.FindOne().SetSkip(2)
// Retrieves a document that matches the filter and prints it as
// a struct
var result Tea
err = coll.FindOne(context.TODO(), filter, opts).Decode(&result)
if err != nil {
	if err == mongo.ErrNoDocuments {
		fmt.Println("No documents found")
	} else {
		panic(err)
	}
}
res, _ := bson.MarshalExtJSON(result, false, false)
fmt.Println(string(res))

{"item":"Masala","rating":9,"date_ordered":"2009-11-12T05:00:00Z"}

Encontre um por exemplo de ObjectId

Este exemplo define uma variável id com um valor do tipo ObjectId e utiliza id para especificar um filtro de query. O filtro corresponde a um documento com um valor de campo _id que corresponde à variável id. Este exemplo query o seguinte documento com base em seu valor _id:

 {
     _id: ObjectId('65170b42b99efdd0b07d42de'),
     item: "Hibiscus",
     rating : 4,
     date_ordered : 2009-12-18T05:00:00.000+00:00
 }

O código abaixo passa o filtro e uma instância do FindOneOptions como parâmetros para o método do FindOne() para executar as seguintes ações:

Combine o documento com o valor de ObjectId especificado
Projete somente os campos Item e Rating do documento correspondente

id, err := bson.ObjectIDFromHex("65170b42b99efdd0b07d42de")
if err != nil {
	panic(err)
}
//  Creates a filter to match a document that has the specified
//  "_id" value
filter := bson.D{{"_id", id}}
opts := options.FindOne().SetProjection(bson.D{{"item", 1}, {"rating", 1}})
// Retrieves a document that matches the filter and prints it as
// a struct
var result Tea
err = coll.FindOne(context.TODO(), filter, opts).Decode(&result)
if err != nil {
	if err == mongo.ErrNoDocuments {
		fmt.Println("No documents found")
	} else {
		panic(err)
	}
}
res, _ := bson.MarshalExtJSON(result, false, false)
fmt.Println(string(res))

{"item":"Hibiscus","rating":4}

Observação

O driver Go gera automaticamente um valor ObjectId exclusivo para cada campo _id do documento, portanto, seu valor ObjectId pode ser diferente do exemplo de código anterior. Para obter mais informações sobre o campo _id, consulte a seção _id Field da página Inserir um documento.

Operações de agregação

Use operações de aggregation para recuperar e transformar dados do MongoDB. Execute operações de aggregation usando o método Aggregate().

Agregação

O método Aggregate() espera que você passe um tipo Context e um pipeline de agregação. Um pipeline de agregação define como transformar dados por meio de estágios. Algumas das etapas são combinar documentos, renomear campos e agrupar valores.

O método retorna os documentos resultantes em um tipo Cursor. Se você omitir o estágio $match, o pipeline continuará usando todos os documentos da coleção.

Para saber como acessar dados em um cursor, consulte Como acessar dados de um cursor.

Modificar comportamento

O método Aggregate() opcionalmente usa um tipo AggregateOptions , que representa opções que você pode usar para modificar seu comportamento. Se você não especificar nenhuma opção, o driver usará os valores padrão para cada opção.

O tipo AggregateOptions permite a você configurar opções com os seguintes métodos:

Método	Descrição
`SetAllowDiskUse()`	Whether to write to temporary files. Default: `false`
`SetBatchSize()`	The number of documents to return in each batch. Default: none
`SetBypassDocumentValidation()`	Whether to allow the write to opt-out of document level validation. Default: `false`
`SetCollation()`	The type of language collation to use when sorting results. Default: `nil`
`SetMaxAwaitTime()`	The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. Default: `nil`
`SetComment()`	An arbitrary string or document that allows you to trace the operation through the database profiler, currentOp, and logs. Default: `""`
`SetHint()`	The index to use to scan for documents to retrieve. Default: `nil`
`SetLet()`	Specifies parameters for the aggregate expression, which improves command readability by separating the variables from the query text. Default: none

Exemplo

O exemplo abaixo passa um contexto e uma aggregation pipeline que executa as seguintes ações:

Agrupa avaliações por item pedido
Calcula a classificação média para cada item

groupStage := bson.D{
	{"$group", bson.D{
		{"_id", "$item"},
		{"average", bson.D{
			{"$avg", "$rating"},
		}},
	}}}
cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{groupStage})
if err != nil {
	panic(err)
}
// Prints the average "rating" for each item
var results []bson.M
if err = cursor.All(context.TODO(), &results); err != nil {
	panic(err)
}
for _, result := range results {
	fmt.Printf("%v had an average rating of %v \n", result["_id"], result["average"])
}

Sencha had an average rating of 8.5
Hibiscus had an average rating of 4
Masala had an average rating of 9

Para saber mais sobre como construir um pipeline de agregação, consulte a página manual do servidor MongoDB em Agregação.

Informações adicionais

Para obter exemplos executáveis das operações de localização, consulte os seguintes exemplos de uso:

Para saber mais sobre as operações mencionadas, consulte os seguintes guias:

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

MongoDB go driver