Especifique documentos a serem devolvidos

Visão geral

Neste guia, você pode aprender como especificar quais documentos retornar de uma operação de leitura usando os seguintes métodos:

SetSort(): especifica a ordem de classificação para os documentos devolvidos.
SetSkip(): especifica o número de documentos a ignorar antes de retornar os resultados da query.
SetLimit(): especifica o número máximo de documentos para retornar de uma query.

Dados de amostra

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

type Course struct {
	Title      string
	Enrollment int32
}

Para executar os exemplos neste guia, carregue os dados de amostra na collection db.courses usando o seguinte trecho:

coll := client.Database("db").Collection("courses")
docs := []interface{}{
	Course{Title: "World Fiction", Enrollment: 35},
	Course{Title: "Abstract Algebra", Enrollment: 60},
	Course{Title: "Modern Poetry", Enrollment: 12},
	Course{Title: "Plate Tectonics", Enrollment: 35},
}
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 representa uma descrição de um curso universitário e inclui o nome do curso e o número máximo de matrículas, correspondentes aos campos title e enrollment em cada documento.

Sort

Para especificar a ordem dos seus resultados, passe uma interface especificando os campos de classificação e direção para o método SetSort() das opções de uma operação.

As seguintes operações aceitam SetSort() como uma opção:

Find()
FindOne()
FindOneAndDelete()
FindOneAndUpdate()
FindOneAndReplace()
GridFSBucket.Find()

Você pode configurar uma direção de classificação ascendente ou descendente.

Ascendente

Uma classificação crescente ordena seus resultados do menor para o maior. Para especificar esta classificação, passe o campo pelo qual você deseja classificar e 1 para o método SetSort().

Dica

Com uma classificação ascendente, o método ordena valores do tipo Boolean de false a true, valores do tipo String de a a z e valores do tipo numérico de infinito negativo a infinito positivo.

O exemplo a seguir especifica uma classificação crescente no campo enrollment:

filter := bson.D{}
opts := options.Find().SetSort(bson.D{{"enrollment", 1}})
cursor, err := coll.Find(context.TODO(), filter, opts)
var results []Course
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))
}

{"title":"Modern Poetry","enrollment":12}
{"title":"World Fiction","enrollment":35}
{"title":"Plate Tectonics","enrollment":35}
{"title":"Abstract Algebra","enrollment":60}

Descendente

Uma classificação decrescente ordena seus resultados do maior para o menor. Para especificar essa classificação, passe o campo pelo qual você deseja classificar e -1 para o método SetSort().

Dica

Com uma classificação decrescente, o método ordena valores de tipo Boolean de true para false, String valores de tipo de z para um e valores de tipo numérico de infinito positivo para infinito negativo.

O exemplo seguinte especifica uma classificação decrescente no campo enrollment:

filter := bson.D{}
opts := options.Find().SetSort(bson.D{{"enrollment", -1}})
cursor, err := coll.Find(context.TODO(), filter, opts)
var results []Course
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))
}

{"title":"Abstract Algebra","enrollment":60}
{"title":"World Fiction","enrollment":35}
{"title":"Plate Tectonics","enrollment":35}
{"title":"Modern Poetry","enrollment":12}

Lidar com empates

Um empate ocorre quando dois ou mais documentos têm valores idênticos no campo que você está usando para classificar seus resultados. O MongoDB não garante a ordem se ocorrerem empates.

Por exemplo, nos dados de amostra, há uma vínculo para enrollment nos seguintes documentos:

{"title":"World Fiction","enrollment":35}
{"title":"Plate Tectonics","enrollment":35}

Você pode classificar campos adicionais para resolver empates na classificação original. Para garantir um pedido específico de documentos, selecione os campos de classificação que não resultem em empates.

O exemplo a seguir especifica uma classificação descendente no campo enrollment e, em seguida, uma classificação ascendente no campo title :

filter := bson.D{}
opts := options.Find().SetSort(bson.D{{"enrollment", -1}, {"title", 1}})
cursor, err := coll.Find(context.TODO(), filter, opts)
var results []Course
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))
}

{"title":"Abstract Algebra","enrollment":60}
{"title":"Plate Tectonics","enrollment":35}
{"title":"World Fiction","enrollment":35}
{"title":"Modern Poetry","enrollment":12}

Agregação

Você também pode incluir o estágio $sort para especificar uma classificação em um pipeline de agregação.

O exemplo a seguir especifica uma classificação descendente no campo enrollment e, em seguida, uma classificação ascendente no campo title :

sortStage := bson.D{{"$sort", bson.D{{"enrollment", -1}, {"title", 1}}}}
cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{sortStage})
if err != nil {
    panic(err)
}
var results []Course
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))
}

{"title":"Abstract Algebra","enrollment":60}
{"title":"Plate Tectonics","enrollment":35}
{"title":"World Fiction","enrollment":35}
{"title":"Modern Poetry","enrollment":12}

Ignorar

Para ignorar um número especificado de resultados retornados de uma query, passe o número de documentos que você deseja ignorar para o método SetSkip() das opções da operação de leitura.

As seguintes operações de leitura utilizam o SetSkip() como uma opção:

Find()
FindOne()
CountDocuments()
GridFSBucket.Find()

Se o número de documentos exceder o número de documentos correspondentes para uma query, essa query não retornará nenhum documento.

Encontre operações que retornam documento em uma ordem de armazenamento que não está classificada em nenhum campo. Para evitar ignorar documentos aleatórios, utilize o método SetSort() para classificar documentos em um campo com valores únicos antes de definir uma opção ignorar.

O seguinte exemplo executa uma operação do Find() com o seguinte comportamento:

Classifica os resultados em ordem crescente no campo enrollment
Pula os dois primeiros documentos

opts := options.Find().SetSort(bson.D{{"enrollment", 1}}).SetSkip(2)
cursor, err := coll.Find(context.TODO(), bson.D{}, opts)
var results []Course
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))
}

{"title":"Plate Tectonics","enrollment":35}
{"title":"Abstract Algebra","enrollment":60}

Agregação

Você também pode incluir o estágio $skip em um pipeline de agregação para pular documentos.

O seguinte exemplo executa uma operação do Aggregate() com o seguinte comportamento:

Classifica os resultados em ordem decrescente no campo enrollment
Pula o primeiro documento

sortStage := bson.D{{"$sort", bson.D{{"enrollment", -1}}}}
skipStage := bson.D{{"$skip", 1}}
cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{sortStage, skipStage})
if err != nil {
    panic(err)
}
var results []Course
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))
}

{"title":"Plate Tectonics","enrollment":35}
{"title":"World Fiction","enrollment":35}
{"title":"Modern Poetry","enrollment":12}

Limite

Para limitar o número de documentos retornados de uma consulta, passe o número de documentos que você deseja retornar ao método SetLimit() das opções da operação de leitura.

As seguintes operações de leitura utilizam o SetLimit() como uma opção:

Find()
CountDocuments()
GridFSBucket.Find()

Se o limite for 0 ou exceder o número de documentos correspondentes, o método retornará todos os documentos. Se o limite for um número negativo, o método usará o valor absoluto do número negativo como limite e fechará o cursor após a recuperação dos documentos.

O exemplo a seguir mostra como retornar dois documentos que têm um valor de campo enrollment maior que 20:

filter := bson.D{{"enrollment", bson.D{{"$gt", 20}}}}
opts := options.Find().SetLimit(2)
cursor, err := coll.Find(context.TODO(), filter, opts)
var results []Course
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))
}

{"title":"World Fiction","enrollment":35}
{"title":"Abstract Algebra","enrollment":60}

Várias Opções

O driver executa o comportamento do limite por último, independentemente da ordem em que você define as outras opções. Por exemplo, as seguintes configurações de opção produzem o mesmo resultado, independentemente da ordem em que SetLimit() é chamado:

opts := options.Find().SetSort(bson.D{{"enrollment", -1}}).SetSkip(1).SetLimit(2)
opts := options.Find().SetLimit(2).SetSort(bson.D{{"enrollment", -1}}).SetSkip(1)

O seguinte exemplo executa uma operação do Find() com o seguinte comportamento:

Classifica os resultados em ordem decrescente no campo enrollment
Pula o primeiro documento
Retorna os dois primeiros documentos restantes

filter := bson.D{}
opts := options.Find().SetSort(bson.D{{"enrollment", -1}}).SetLimit(2).SetSkip(1)
cursor, err := coll.Find(context.TODO(), filter, opts)
var results []Course
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))
}

{"title":"Abstract Algebra","enrollment":60}
{"title":"Plate Tectonics","enrollment":35}

Agregação

Você também pode incluir o estágio $limit para especificar um limite em um pipeline de agregação.

O exemplo a seguir mostra como gerar três documentos:

limitStage := bson.D{{"$limit", 3}}
cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{limitStage})
if err != nil {
    panic(err)
}
var results []Course
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))
}

{"title":"World Fiction","enrollment":35}
{"title":"Abstract Algebra","enrollment":60}
{"title":"Modern Poetry","enrollment":12}

Informações adicionais

Para saber mais sobre as operações abordadas neste guia, consulte a seguinte documentação:

Para saber como classificar as pontuações de textos da sua pesquisa de textos, consulte Fazer uma pesquisa de texto.

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:

Voltar

Acessar dados de um cursor

Especifique campos a serem retornados