/**
* Lookup records by key
*
* @param Key[] $keys The identifiers to look up.
* @param array $options [optional] {
* Configuration Options
*
* @type string $readConsistency See
* [ReadConsistency](https://cloud.google.com/datastore/reference/rest/v1/ReadOptions#ReadConsistency).
* @type string $transaction The transaction ID, if the query should be
* run in a transaction.
* @type string|array $className If a string, the name of the class to return results as.
* Must be a subclass of {@see Google\Cloud\Datastore\Entity}.
* If not set, {@see Google\Cloud\Datastore\Entity} will be used.
* If an array is given, it must be an associative array, where
* the key is a Kind and the value is the name of a subclass of
* {@see Google\Cloud\Datastore\Entity}.
* @type bool $sort If set to true, results in each set will be sorted
* to match the order given in $keys. **Defaults to** `false`.
* }
* @return array Returns an array with keys [`found`, `missing`, and `deferred`].
* Members of `found` will be instance of
* {@see Google\Cloud\Datastore\Entity}. Members of `missing` and
* `deferred` will be instance of {@see Google\Cloud\Datastore\Key}.
* @throws InvalidArgumentException
*/
public function lookup(array $keys, array $options = [])
{
$options += ['className' => null, 'sort' => false];
$this->validateBatch($keys, Key::class, function ($key) {
if ($key->state() !== Key::STATE_NAMED) {
throw new InvalidArgumentException(sprintf('Given $key is in an invalid state. Can only lookup records when given a complete key. ' . 'Given path was %s', (string) $key));
}
});
$res = $this->connection->lookup($options + $this->readOptions($options) + ['projectId' => $this->projectId, 'keys' => $keys]);
$result = [];
if (isset($res['found'])) {
$result['found'] = $this->mapEntityResult($res['found'], $options['className']);
if ($options['sort']) {
$result['found'] = $this->sortEntities($result['found'], $keys);
}
}
if (isset($res['missing'])) {
$result['missing'] = [];
foreach ($res['missing'] as $missing) {
$key = $this->key($missing['entity']['key']['path'], $missing['entity']['key']['partitionId']);
$result['missing'][] = $key;
}
}
if (isset($res['deferred'])) {
$result['deferred'] = [];
foreach ($res['deferred'] as $deferred) {
$key = $this->key($deferred['path'], $deferred['partitionId']);
$result['deferred'][] = $key;
}
}
return $result;
}
