Visão geral
Neste guia, você pode aprender como usar o PyMongo, o driver Python síncrono do MongoDB, para recuperar dados de uma coleção do MongoDB usando operações de leitura. Você pode chamar o método find() ou find_one() para recuperar documentos que correspondam a um conjunto de critérios.
Dados de amostra
Os exemplos neste guia usam a collection sample_restaurants.restaurants dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o tutorial Introdução ao PyMongo .
Encontrando documentos
O PyMongo inclui dois métodos para recuperar documentos de uma collection: find_one() e find(). Esses métodos usam um filtro de query e retornam um ou mais documentos correspondentes. Um filtro de query é um objeto que especifica os documentos que você deseja recuperar em sua query.
Para saber mais sobre filtros de queries, consulte Especificar uma query.
Encontrar um documento
Para localizar um único documento em uma coleção, chame o método find_one() e passe um filtro de query que especifique os critérios do documento que você deseja localizar. Se mais de um documento corresponder ao filtro de query, esse método retornará o primeiro documento correspondente dos resultados recuperados como um dicionário Python. Se nenhum documento corresponder ao filtro de query, o método retornará None.
Dica
O método find_one() é útil quando você sabe que há apenas um documento correspondente ou só está interessado na primeira correspondência.
O exemplo a seguir usa o método find_one() para localizar o primeiro documento em que o campo "cuisine" tem o valor "Bakery". Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:
restaurant = sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})
restaurant = await sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})
Dica
Ordem de classificação
O método find_one() retorna o primeiro documento em ordem natural no disco se nenhum critério de classificação for especificado.
Para saber mais sobre classificação, consulte o guia de classificação .
Localizar vários documentos
Para encontrar vários documentos em uma coleção, passe um filtro de queries para o método find() que especifica os critérios dos documentos que você deseja recuperar.
O exemplo seguinte utiliza o método find() para localizar todos os documentos onde o campo "cuisine" tem o valor "Spanish".
cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"})
Você pode utilizar um cursor para iterar nos documentos retornados pelo método find(). Um cursor é um mecanismo que permite que um aplicativo itere sobre os resultados do banco de dados enquanto mantém apenas um subconjunto deles na memória em determinado momento. Os cursores são úteis quando o método find() retorna uma grande quantidade de documentos.
Você pode iterar sobre os documentos em um cursor usando um loop for-in, conforme mostrado no exemplo a seguir. Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:
cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"}) for restaurant in cursor: ...
cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"}) async for restaurant in cursor: ...
Observação
Localizar todos os documentos
Para encontrar todos os documentos em uma coleção, passe um filtro vazio para o método find() :
all_restaurants = sample_restaurants.restaurants.find({})
Modificar comportamento de localização
Você pode modificar o comportamento dos métodos find() e find_one() passando argumentos nomeados para eles. A tabela a seguir descreve os argumentos comumente usados:
Argument | Descrição |
|---|---|
| Limits the number of documents to hold in a cursor at a given time. |
| The collation options for the find operation. See the Collation
guide for more information. |
| A string to attach to the query. This can help you trace and interpret the
operation in the server logs and in profile data. To learn more about query comments,
see the cursor.comment() page in the
MongoDB Server manual. |
| The index to use for the query. |
| The maximum execution time on the server for this operation. If this time is
exceeded, PyMongo aborts the operation and raises an ExecutionTimeout. |
O exemplo a seguir usa o método find() para localizar todos os documentos onde o campo "cuisine" tem o valor "Italian" e define um tempo máximo de execução de 10 segundos (10,000 milissegundos):
cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000)
Para obter uma lista completa dos argumentos disponíveis, consulte a documentação da API para o find() method.
Agrupamentos
Ao executar uma query, você pode especificar um agrupamento para o driver seguir ao classificar os resultados.
Um agrupamento é um conjunto de regras específicas do idioma para comparação de cadeias de caracteres, como para letras maiúsculas e minúsculas e acentos.
Para especificar um agrupamento, crie uma instância da classe Collation ou um dicionário Python. Para obter uma lista de opções a serem passadas para o construtor Collation ou incluídas como chaves no dicionário, consulte Agrupamento no manual do MongoDB Server.
Dica
Importar agrupamento
Para criar uma instância da classe Collation, você deve importá-la do pymongo.collation.
O exemplo a seguir executa a mesma operação de localização do exemplo anterior, mas com um agrupamento padrão de fr_CA:
cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000, collation=Collation(locale="fr_CA"))
Como alternativa, você pode especificar um agrupamento encadeando o método collation() ao método find():
cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000) .collation(Collation(locale="fr_CA")
Observação
O agrupamento de operações substitui o padrão
Quando você especifica um agrupamento como parte de uma operação, ele substitui o agrupamento padrão para a coleção.
Informações adicionais
A biblioteca PyMongoArrow permite carregar conjuntos de resultados de query do MongoDB como Pandas DataFrames, NumPy ndarays ou Apache Arrow Tables. Para saber mais sobre o PyMongoArrow, consulte a documentação do PyMongoArrow.
Para saber mais sobre filtros de queries, consulte Especificar uma query.
Para obter exemplos de código executáveis de recuperação de documentos com o PyMongo, consulte Query.
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: