Acessar dados de um cursor

Visão geral

Neste guia, você pode aprender como acessar dados de um cursor usando a Biblioteca PHP do MongoDB .

Um cursor é um mecanismo que retorna os resultados de uma operação de leitura em lotes iteráveis. Os cursores reduzem o consumo de memória e o número de solicitações do servidor , mantendo apenas um subconjunto de documentos a qualquer momento, em vez de retornar todos os documentos de uma só vez.

Sempre que a Biblioteca PHP MongoDB executa uma operação de leitura utilizando o método MongoDB\Collection::find() , ela retorna os documentos correspondentes em uma instância do MongoDB\Driver\Cursor .

$collection = $client->sample_restaurants->restaurants;

Acesse o conteúdo do cursor iterativamente

A classe MongoDB\Driver\Cursor implementa a interface Iterator , portanto, você pode usar um loop foreach para iterar por seu conteúdo.

O exemplo a seguir usa o método MongoDB\Collection::find() para recuperar todos os documentos nos quais o valor do campo name é 'Dunkin' Donuts'. Em seguida, ele imprime cada documento do cursor retornado pelo método find() :

$cursor = $collection->find(['name' => 'Dunkin\' Donuts']);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

Recuperar documentos individualmente

Para recuperar um documento individual de um cursor, chame o método current() em uma instância MongoDB\Driver\Cursor . Este método retorna o documento para o qual o cursor aponta inicialmente. Você pode continuar avançando o cursor chamando o método next() , que instrui o cursor a ponto para o próximo documento recuperado.

O exemplo a seguir encontra todos os documentos em que o valor do campo name é 'Dunkin' Donuts'. Em seguida, ele imprime o primeiro documento recuperado chamando o método current() em um cursor:

$cursor = $collection->find(['name' => 'Dunkin\' Donuts']);
$cursor->rewind();
echo json_encode($cursor->current());

Recuperar todos os documentos

Para recuperar todos os documentos de um cursor, converta o cursor em uma array usando um dos seguintes métodos:

• MongoDB\\Driver\\Cursor::toArray(): Chame um objeto MongoDB\Driver\Cursor

• iterator_to_array(): Passe um objeto MongoDB\Driver\Cursor como parâmetro

O exemplo seguinte chama o método toArray() em um cursor para armazenar seus resultados em uma array:

$cursor = $collection->find(['name' => 'Dunkin\' Donuts']);
$array_results = $cursor->toArray();

Cursores persistentes

Ao fazer query em uma collection limitada, você pode usar um cursor persistente que permanece aberto depois que o cliente esgota os resultados em um cursor. Para criar um cursor persistente, defina a opção cursorType como MongoDB\Operation\Find::TAILABLE em uma array. Em seguida, passe a array como um parâmetro de opções para o método MongoDB\Collection::find() .

Por exemplo, você pode criar uma collection limitada chamada vegetables que armazena documentos que representam Legumes, conforme mostrado no código a seguir:

$db = $client->db;
$create_coll = $db->createCollection(
    'vegetables', 
    ['capped' => true, 'size' => 1024 * 1024]
);
$vegetables = [
    ['name' => 'cauliflower'],
    ['name' => 'zucchini']
];
$collection = $db->vegetables;
$result = $collection->insertMany($vegetables);

O código a seguir usa um cursor persistente para recuperar todos os documentos na coleção vegetables . Depois que o cursor estiver esgotado, ele permanecerá aberto até a recuperação de três documentos:

$cursor = $collection->find([], ['cursorType' => MongoDB\Operation\Find::TAILABLE]);
$cursor->rewind();
$docs_found = 0;
while ($docs_found < 3) {
    if ($cursor->valid()) {
        $doc = $cursor->current();
        echo json_encode($doc), PHP_EOL;
        $docs_found++;
    }
    $cursor->next();
}

Se você inserir outro documento na coleção vegetables , o código anterior imprimirá o novo documento e fechará o loop while .

Para saber mais sobre cursores tailable, consulte Cursores tailable no manual do MongoDB Server .

Informações adicionais

Para saber mais sobre operações de leitura, consulte o guia Recuperar dados .

Para saber mais sobre cursores, consulte as seguintes páginas na documentação da API da extensão:

• MongoDB\Driver\cursor

• MongoDB\Driver\Cursor::current()

• MongoDB\Driver\Cursor::toArray()

• iterator_to_array()