Menu Docs
Página inicial do Docs
/
Idiomas
/
PHP
/
Manual da Biblioteca PHP

Executar um comando de banco de dados

Nesta página

  • Visão geral
  • Executar um comando
  • Resposta
  • Exemplo de comando
  • Informações adicionais
  • Documentação da API

Visão geral

Neste guia, você pode aprender como usar a Biblioteca MongoDB PHP 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 .

Importante

Preferir métodos de biblioteca a comandos de banco de dados

A biblioteca fornece métodos wrapper para muitos comandos de banco de dados de dados. Recomendamos usar esses métodos em vez de executar comandos do banco de dados de dados quando possível.

Para executar tarefas administrativas, use o MongoDB Shell em vez da Biblioteca MongoDB PHP. O shell fornece métodos assistente que podem não estar disponíveis na biblioteca.

Se não houver auxiliares disponíveis na biblioteca ou no shell, você poderá usar o método de shell db.runCommand() ou o método MongoDB\Database::command() da biblioteca, descrito neste guia.

Executar um comando

Para executar um comando de banco de dados de dados, você deve especificar o comando e quaisquer parâmetros relevantes em um documento de comando e, em seguida, passar o documento de comando para o método MongoDB\Database::command() . Muitos comandos de banco de dados de dados retornam vários documentos de resultado, portanto, o command() método retorna um MongoDB\Driver\Cursor objeto pelo qual você pode iterar.

O código a seguir mostra como usar o método command() em uma instância MongoDB\Database para executar o comando hello , que retorna informações sobre o servidor:

$database = $client->selectDatabase('myDB');
$cursor = $database->command(['hello' => 1]);

Para encontrar um link para uma lista completa de comandos de banco de dados e parâmetros correspondentes, consulte a seção Informações adicionais.

Observação

readPreference

O método command() não herda a preferência de leitura que você pode ter definido na instância Database em outro lugar do código. Por padrão, o command() utiliza a preferência de leitura primary .

Você pode definir uma preferência de leitura para a execução do comando definindo uma no parâmetro de opções, conforme mostrado no código a seguir:

$readPref = new MongoDB\Driver\ReadPreference('primaryPreferred');
$cursor = $database->command(
    ['hello' => 1], 
    ['readPreference' => $readPref]
);

Saiba mais sobre a ReadPreference classe na documentação da API de extensão PHP.

Para saber mais sobre as opções de preferência de leitura , consulte Read preference no manual do MongoDB Server .

Resposta

O método command() retorna um objeto Cursor que contém a resposta do banco de banco de dados para o comando fornecido. Cada comando de banco de dados de dados executa uma função diferente, portanto, o conteúdo da resposta pode variar.

Para comandos que retornam um único documento de resultado, esse resultado está disponível como o primeiro e único documento no cursor. Para comandos que retornam vários documentos de resultado, a biblioteca converte o envelope do cursor na resposta bruta do comando, que inclui o ID do cursor e o primeiro lote de resultados, em um cursor iterável.

Antes de executar um comando, saiba mais sobre o formato de resposta do comando para que seu aplicação itere por vários resultados ou extraia o primeiro e único documento no cursor. Consulte a seção Informações adicionais deste guia para encontrar um link para a lista completa de comandos do banco de dados de dados.

A resposta bruta do comando contém os seguintes campos:

Campo
Descrição

<command result>

Campos específicos do comando de banco de dados de dados. Por exemplo, o comando count retorna o campo n .

ok

Se o comando foi bem-sucedido (1) ou falhou (0). A biblioteca gera uma CommandException se o ok campo for 0.

operationTime

A hora lógica da operação. O MongoDB usa o tempo lógico para solicitar operações. Para saber mais sobre esse conceito, consulte nosso blog post sobre o Global Logical clock.

$clusterTime

Um documento que contém o tempo de cluster assinado. O tempo do cluster é um tempo lógico usado para ordenar operações.

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 accounts :

$database = $client->accounts;
$command = ['dbStats' => 1];
// dbStats returns a single document
$cursor = $database->command($command);
// Print the first document in the cursor
echo json_encode($cursor->toArray()[0]), PHP_EOL;

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

{"db":"accounts","collections":2,"views":0,"objects":5,"avgObjSize":22,"dataSize":110,
"storageSize":40960,"totalFreeStorageSize":0,"numExtents":0,"indexes":2,"indexSize":40960,
"indexFreeStorageSize":0,"fileSize":0,"nsSizeMB":0,"ok":1}

Informações adicionais

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

Documentação da API

Para obter mais informações sobre o método command() , consulte a seguinte documentação da API da biblioteca PHP do MongoDB :

Voltar

Operações CRUD e conjuntos de réplicas

Próximo

aggregation de dados