Executar um comando de banco de dados

Visão geral

Neste guia, você pode aprender como usar o PyMongo para executar um comando de banco de dados de dados. Você pode usar comandos de banco de dados de dados para executar uma variedade de tarefas administrativas e de diagnóstico, como buscar estatísticas do servidor , inicializar um conjunto de réplicas ou executar um pipeline de agregação .

Executar um comando

Você pode utilizar o método command() para executar um comando de banco de dados de dados. Você deve especificar o comando e quaisquer argumentos relevantes. Se o comando for simples, eles podem ser passados como strings. Caso contrário, eles podem ser passados como um objeto dict. O método retornará o resultado do comando que foi executado.

O seguinte código mostra como você pode utilizar o método command() em um Database para executar o comando hello, que retorna informações sobre o servidor:

database = client.get_database("my_db")
hello = database.command("hello")
print(hello)

{
    'topologyVersion': {
        'processId': ObjectId('6724d211d6b98fa1931e8616'),
        'counter': 6
    },
    'hosts': ['cluster0-shard-00-00.fxoii.mongodb.net:27017',
            'cluster0-shard-00-01.fxoii.mongodb.net:27017',
            'cluster0-shard-00-02.fxoii.mongodb.net:27017'],
    'setName': 'atlas-13l6uw-shard-0',
    'setVersion': 114,
    'isWritablePrimary': True,
    'secondary': False,
    'primary': 'cluster0-shard-00-02.fxoii.mongodb.net:27017',
    'tags': {
        'workloadType': 'OPERATIONAL',
        'diskState': 'READY',
        'region': 'US_EAST_1',
        'provider': 'AWS',
        'nodeType': 'ELECTABLE',
        'availabilityZone': 'use1-az5'
    },
    'me': 'cluster0-shard-00-02.fxoii.mongodb.net:27017',
    'electionId': ObjectId('7fffffff00000000000000e3'),
    'lastWrite': {
        'opTime': {
            'ts': Timestamp(1730486145, 22),
            't': 227
        },
        'lastWriteDate': datetime.datetime(2024, 11, 1, 18, 35, 45),
        'majorityOpTime': {
            'ts': Timestamp(1730486145, 22),
            't': 227
        },
        'majorityWriteDate': datetime.datetime(2024, 11, 1, 18, 35, 45)
    },
    'maxBsonObjectSize': 16777216,
    'maxMessageSizeBytes': 48000000,
    'maxWriteBatchSize': 100000,
    'localTime': datetime.datetime(2024, 11, 1, 18, 35, 45, 309000),
    'logicalSessionTimeoutMinutes': 30,
    'connectionId': 23889,
    'minWireVersion': 0,
    'maxWireVersion': 21,
    'readOnly': False,
    'ok': 1.0,
    '$clusterTime': {
        'clusterTime': Timestamp(1730486145, 22),
        'signature': {
            'hash': b"\x1a\xf7{>q%F\xc2\x89\x15\x13W29\x91\xaae'~\xe4",
            'keyId': 7379292132843978793
        }
    },
    'operationTime': Timestamp(1730486145, 22)
}

Para obter uma lista completa dos comandos do banco de dados e dos parâmetros correspondentes, consulte a seção Informações adicionais.

Cursor de comando

O método command() retorna o resultado do comando que foi executado. Você também pode usar o cursor_command() método, que emite um comando MongoDB e analisa a resposta como um CommandCursor. O CommandCursor pode ser utilizado para iterar sobre os resultados do comando.

O exemplo seguinte utiliza o método cursor_command() no banco de banco de dados sample_mflix. Ele executa o comando find na collection movies para filtrar por documentos nos quais o campo runtime tem valor de 11.

database = client.get_database("sample_mflix")
result = database.cursor_command("find", "movies", filter={"runtime": 11})
print(result.to_list())

{
    '_id': ObjectId('573a1390f29313caabcd42e8'),
    'runtime': 11,
    'title': 'The Great Train Robbery',
    ...
},
{
    {'_id': ObjectId('573a1394f29313caabce0f10'),
    'runtime': 11,
    'title': 'Glas',
    ...
},
...

Para saber mais sobre o formato de resposta do comando, consulte Comandos do banco de dados.

from pymongo.read_preferences import Secondary
database = client.get_database("my_db")
hello = database.command("hello", read_preference=Secondary())
print(hello)

Exemplo de comando

O exemplo seguinte utiliza o método command() para executar o comando dbStats para recuperar estatísticas de armazenamento para o banco de banco de dados do sample_mflix :

database = client.get_database("sample_mflix")
result = database.command("dbStats")
print(result)

{'db': 'sample_mflix', 'collections': 9, 'views': 1, 'objects': 67662,
'avgObjSize': 1796.788182436227, 'dataSize': 121574282, 'storageSize': 97779712,
'totalFreeStorageSize': 0, 'numExtents': 0, 'indexes': 13, 'indexSize': 19423232,
'indexFreeStorageSize': 0, 'fileSize': 0, 'nsSizeMB': 0, 'ok': 1}

A saída desse comando inclui informações sobre as collections no banco de dados de dados e descreve a quantidade e o tamanho dos dados armazenados nas collections.

Dicas de tipo

O método Database.command() pode decodificar os documentos BSON retornados para instâncias de uma classe específica. Para especificar essa classe, construa um objeto CodecOptions e passe o nome da classe . A classe pode ser um dos seguintes tipos:

• bson.raw_bson.RawBSONDocument. Para saber mais sobre a classe RawBSONDocument, consulte Trabalhar com dados brutos BSON.

• Uma subclasse do tipo collections.abc.Mapping, como OrderedDict. Dependendo do detalhamento de suas regras de verificação de tipo, talvez você também precise especificar tipos para a chave e o valor.

• Uma subclasse do tipo TypedDict. Para passar uma subclasse TypedDict para esse parâmetro, você também deve incluir a classe em uma dica de tipo para seu objeto CodecOptions.

O exemplo seguinte decodifica o BSON retornado pelo comando ping para instâncias da classe RawBSONDocument :

from pymongo import MongoClient
from bson.raw_bson import RawBSONDocument
from bson import CodecOptions
client: MongoClient = MongoClient()
options = CodecOptions(RawBSONDocument)
result = client.admin.command("ping", codec_options=options)

Para decodificar BSON para uma subclasse da classe TypedDict, especifique o nome da classe na dica de tipo CodecOptions, como mostrado no seguinte exemplo:

from pymongo import MongoClient
from bson.raw_bson import RawBSONDocument
from bson import CodecOptions
from typing import TypedDict
class Movie(TypedDict):
    name: str
    year: int
client: MongoClient = MongoClient()
options: CodecOptions[Movie] = CodecOptions(Movie)
result = client.admin.command("ping", codec_options=options)

Solução de problemas

from pymongo import MongoClient
client = MongoClient()  # error: Need type annotation for "client"

error: Dict entry 0 has incompatible type "str": "int";
expected "Mapping[str, Any]": "int"

``client: MongoClient[Dict[str, Any]]``

Informações adicionais

Para obter mais informações sobre os conceitos deste guia, consulte a seguinte documentação no manual do MongoDB Server :

• db.runCommand()

• Comandos de banco de dados

• olá comando

• Encontre o comando

• Comando dbStats