Cloud Datastore Client - Class DatastoreClient (1.26.0)

Reference documentation and code samples for the Cloud Datastore Client class DatastoreClient.

Google Cloud Datastore is a highly-scalable NoSQL database for your applications. Find more information at the Google Cloud Datastore docs.

Cloud Datastore supports multi-tenant applications through use of data partitions. A partition ID can be supplied when creating an instance of Cloud Datastore, and will be used in all operations executed in that instance.

To enable the Google Cloud Datastore Emulator, set the DATASTORE_EMULATOR_HOST environment variable.

Example:

use Google\Cloud\Datastore\DatastoreClient;

$datastore = new DatastoreClient();

// Multi-tenant applications can supply a namespace ID.
use Google\Cloud\Datastore\DatastoreClient;

$datastore = new DatastoreClient([
    'namespaceId' => 'my-application-namespace'
]);

// Using the Datastore Emulator
use Google\Cloud\Datastore\DatastoreClient;

// Be sure to use the port specified when starting the emulator.
// `8900` is used as an example only.
putenv('DATASTORE_EMULATOR_HOST=localhost:8900');

$datastore = new DatastoreClient();

// Multi-database applications can supply a database ID.
use Google\Cloud\Datastore\DatastoreClient;

$datastore = new DatastoreClient([
    'namespaceId' => 'my-application-namespace',
    'databaseId' => 'my-database'
]);

Namespace

Google \ Cloud \ Datastore

Methods

__construct

Create a Datastore client.

Parameters
Name	Description
`config`	`array` Configuration Options.
`↳ apiEndpoint`	`string` A hostname with optional port to use in place of the service's default endpoint.
`↳ projectId`	`string` The project ID from the Google Developer's Console.
`↳ authCache`	`CacheItemPoolInterface` A cache for storing access tokens. Defaults to a simple in memory implementation.
`↳ authCacheOptions`	`array` Cache configuration options.
`↳ authHttpHandler`	`callable` A handler used to deliver Psr7 requests specifically for authentication.
`↳ credentialsFetcher`	`FetchAuthTokenInterface` A credentials fetcher instance.
`↳ httpHandler`	`callable` A handler used to deliver Psr7 requests. Only valid for requests sent over REST.
`↳ keyFile`	`array` The contents of the service account credentials .json file retrieved from the Google Developer's Console. Ex: `json_decode(file_get_contents($path), true)`.
`↳ keyFilePath`	`string` The full path to your service account credentials .json file retrieved from the Google Developers Console.
`↳ requestTimeout`	`float` Seconds to wait before timing out the request. Defaults to `0` with REST and `60` with gRPC.
`↳ retries`	`int` Number of retries for a failed request. Defaults to `3`.
`↳ scopes`	`array` Scopes to be used for the request.
`↳ quotaProject`	`string` Specifies a user project to bill for access charges associated with the request.
`↳ namespaceId`	`string` Partitions data under a namespace. Useful for Multitenant Projects.
`↳ databaseId`	`string` ID of the database to which the entities belong.
`↳ returnInt64AsObject`	`bool` If true, 64 bit integers will be returned as a Google\Cloud\Core\Int64 object for 32 bit platform compatibility. Defaults to false.

key

See also:

Parameters
Name	Description
`kind`	`string` The kind.
`identifier`	`string\|int` [optional] The ID or name.
`options`	`array` Configuration Options
`↳ identifierType`	`string` If omitted, type will be determined internally. In cases where any ambiguity can be expected (i.e. if you want to create keys with `name` but your values may pass PHP's `is_numeric()` check), this value may be explicitly set using `Key::TYPE_ID` or `Key::TYPE_NAME`.

Returns
Type	Description
`Google\Cloud\Datastore\Key`

keys

See also:

Parameters
Name	Description
`kind`	`string` The kind to use in the final path element.
`options`	`array` Configuration Options
`↳ ancestors`	`array[]` An array of PathElement arrays. Use to create ancestor paths.
`↳ number`	`int` The number of keys to generate.
`↳ id`	`string\|int` The ID for the last pathElement.
`↳ name`	`string` The Name for the last pathElement.

Returns
Type	Description
`array<Google\Cloud\Datastore\Key>`

entity

See also:

Entity

Parameters
Name	Description
`key`	`Google\Cloud\Datastore\Key\|string\|null` [optional] The key used to identify the record, or a string $kind. The key may be null only if the entity will be used as an embedded entity within another entity. Attempting to use keyless entities as root entities will result in error. Defaults to `null`.
`entity`	`array` [optional] The data, provided as an array of keys and values to fill the entity with. Defaults to `[]`.
`options`	`array` Configuration Options
`↳ className`	`string` If set, the given class will be returned. Value must be the name of a class implementing Google\Cloud\Datastore\EntityInterface. Defaults to Google\Cloud\Datastore\Entity.
`↳ excludeFromIndexes`	`array` A list of entity keys to exclude from datastore indexes.

Returns
Type	Description
`Google\Cloud\Datastore\EntityInterface`

geoPoint

See also:

LatLng

Parameters
Name	Description
`latitude`	`float` The latitude
`longitude`	`float` The longitude
`allowNull`	`bool` [optional] Whether null values are allowed. Defaults to `false`.

Returns
Type	Description
`Google\Cloud\Datastore\GeoPoint`

blob

Create a new Blob

Example:

$blob = $datastore->blob('hello world');

// Blobs can be used to store binary data
$blob = $datastore->blob(file_get_contents(__DIR__ .'/family-photo.jpg'));

Parameter
Name	Description
`value`	`string\|resource\|Psr\Http\Message\StreamInterface` The value to store in a blob.

Returns
Type	Description
`Google\Cloud\Datastore\Blob`

int64

Create an Int64 object. This can be used to work with 64 bit integers as a string value while on a 32 bit platform.

Example:

$int64 = $datastore->int64('9223372036854775807');

Parameter
Name	Description
`value`	`string`

Returns
Type	Description
`Google\Cloud\Core\Int64`

cursor

Create a Cursor.

A cursor points to a position within a set of entities. Cloud Datastore uses Cursors for paginating query results.

Example:

$cursor = $datastore->cursor($cursorValue);

Parameter
Name	Description
`cursorValue`	`string\|int`

Returns
Type	Description
`Google\Cloud\Datastore\Cursor`

allocateId

See also:

allocateIds

Parameters
Name	Description
`key`	`Google\Cloud\Datastore\Key` The incomplete key.
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`Google\Cloud\Datastore\Key`

allocateIds

See also:

allocateIds

Parameters
Name	Description
`keys`	`array<Google\Cloud\Datastore\Key>` The incomplete keys.
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`array<Google\Cloud\Datastore\Key>`

transaction

See also:

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ transactionOptions`	`array` Transaction configuration. See ReadWrite.
`↳ databaseId`	`string` ID of the database to which the entities belong.

Returns
Type	Description
`Google\Cloud\Datastore\Transaction`

readOnlyTransaction

See also:

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ transactionOptions`	`array` See ReadOnly.
`↳ databaseId`	`string` ID of the database to which the entities belong.

Returns
Type	Description
`Google\Cloud\Datastore\ReadOnlyTransaction`

insert

See also:

Commit API documentation

Parameters
Name	Description
`entity`	`Google\Cloud\Datastore\EntityInterface` The entity to be inserted.
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`string`	The entity version.

insertBatch

See also:

Commit API documentation

Parameters
Name	Description
`entities`	`array<Google\Cloud\Datastore\EntityInterface>` The entities to be inserted.
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`array`	[Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body)

update

See also:

Commit API documentation

Parameters
Name	Description
`entity`	`Google\Cloud\Datastore\EntityInterface` The entity to be updated.
`options`	`array` Configuration Options
`↳ allowOverwrite`	`bool` Entities must be updated as an entire resource. Patch operations are not supported. Because entities can be created manually, or obtained by a lookup or query, it is possible to accidentally overwrite an existing record with a new one when manually creating an entity. To provide additional safety, this flag must be set to `true` in order to update a record when the entity provided was not obtained through a lookup or query. Defaults to `false`.

Returns
Type	Description
`string`	The entity version.

updateBatch

See also:

Commit API documentation

Parameters
Name	Description
`entities`	`array<Google\Cloud\Datastore\EntityInterface>` The entities to be updated.
`options`	`array` Configuration Options
`↳ allowOverwrite`	`bool` Entities must be updated as an entire resource. Patch operations are not supported. Because entities can be created manually, or obtained by a lookup or query, it is possible to accidentally overwrite an existing record with a new one when manually creating an entity. To provide additional safety, this flag must be set to `true` in order to update a record when the entity provided was not obtained through a lookup or query. Defaults to `false`.

Returns
Type	Description
`array`	[Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body)

upsert

See also:

Commit API documentation

Parameters
Name	Description
`entity`	`Google\Cloud\Datastore\EntityInterface` The entity to be upserted.
`options`	`array` [optional] Configuration Options.

Returns
Type	Description
`string`	The entity version.

upsertBatch

See also:

Commit API documentation

Parameters
Name	Description
`entities`	`array<Google\Cloud\Datastore\EntityInterface>` The entities to be upserted.
`options`	`array` [optional] Configuration Options.

Returns
Type	Description
`array`	[Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body)

delete

See also:

Commit API documentation

Parameters
Name	Description
`key`	`Google\Cloud\Datastore\Key` The identifier to delete.
`options`	`array` Configuration options
`↳ baseVersion`	`string` Provides concurrency control. The version of the entity that this mutation is being applied to. If this does not match the current version on the server, the mutation conflicts.

Returns
Type	Description
`string`	The updated entity version number.

deleteBatch

See also:

Commit API documentation

Parameters
Name	Description
`keys`	`array<Google\Cloud\Datastore\Key>` The identifiers to delete.
`options`	`array` Configuration options
`↳ baseVersion`	`string` Provides concurrency control. The version of the entity that this mutation is being applied to. If this does not match the current version on the server, the mutation conflicts.

Returns
Type	Description
`array`	[Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body)

lookup

See also:

Lookup API documentation

Parameters
Name	Description
`key`	`Google\Cloud\Datastore\Key` The identifier to use to locate a desired entity.
`options`	`array` Configuration Options
`↳ readConsistency`	`string` See ReadConsistency.
`↳ className`	`string` If set, the given class will be returned. Value must be the name of a class implementing Google\Cloud\Datastore\EntityInterface. Defaults to Google\Cloud\Datastore\Entity.
`↳ databaseId`	`string` ID of the database to which the entities belong.
`↳ readTime`	`Timestamp` Reads entities as they were at the given timestamp.

Returns
Type	Description
`Google\Cloud\Datastore\EntityInterface\|null`

lookupBatch

See also:

Lookup API documentation

Parameters
Name	Description
`keys`	`array<Google\Cloud\Datastore\Key>` The identifiers to look up.
`options`	`array` Configuration Options
`↳ readConsistency`	`string` See ReadConsistency.
`↳ className`	`string\|array` If a string, the given class will be returned. Value must be the name of a class implementing Google\Cloud\Datastore\EntityInterface. If an array is given, it must be an associative array, where the key is a Kind and the value must implement Google\Cloud\Datastore\EntityInterface. Defaults to Google\Cloud\Datastore\Entity.
`↳ sort`	`bool` If set to true, results in each set will be sorted to match the order given in $keys. Defaults to `false`.
`↳ databaseId`	`string` ID of the database to which the entities belong.
`↳ readTime`	`Timestamp` Reads entities as they were at the given timestamp.

Returns
Type	Description
`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}.

query

Create a Query object.

The Query class can be used as a builder, or it can accept a query representation at instantiation.

Example:

$query = $datastore->query();

Parameter
Name	Description
`query`	`array` Query

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

aggregationQuery

Create an AggregationQuery object.

In addition to Query features, it supports aggregations.

Example:

$query = $datastore->aggregationQuery();

Parameter
Name	Description
`query`	`array` Query

Returns
Type	Description
`Google\Cloud\Datastore\Query\AggregationQuery`

gqlQuery

Create a GqlQuery object.

Returns a Query object which can be executed using Google\Cloud\Datastore\DatastoreClient::runQuery().

Example:

$query = $datastore->gqlQuery('SELECT * FROM Companies');

// Literals must be provided as bound parameters by default:
$query = $datastore->gqlQuery('SELECT * FROM Companies WHERE companyName = @companyName', [
    'bindings' => [
        'companyName' => 'Google'
    ]
]);

// Positional binding is also supported:
$query = $datastore->gqlQuery('SELECT * FROM Companies WHERE companyName = @1 LIMIT 1', [
    'bindings' => [
        'Google'
    ]
]);

// While not recommended, you can use literals in your query string:
$query = $datastore->gqlQuery('SELECT * FROM Companies WHERE companyName = \'Google\'', [
    'allowLiterals' => true
]);

// Using cursors as query bindings:
$cursor = $datastore->cursor($cursorValue);

$query = $datastore->gqlQuery('SELECT * FROM Companies OFFSET @offset', [
    'bindings' => [
        'offset' => $cursor
    ]
]);

Parameters
Name	Description
`query`	`string` The GQL Query string.
`options`	`array` Configuration Options
`↳ allowLiterals`	`bool` Whether literal values will be allowed in the query string. Parameter binding is strongly encouraged over literals. Defaults to `false`.
`↳ bindings`	`array` An array of values to bind to the query string. Queries using Named Bindings should provide a key/value set, while queries using Positional Bindings must provide a simple array. Query cursors may be provided using instances of Google\Cloud\Datastore\Cursor.
`↳ readConsistency`	`string` See ReadConsistency.

Returns
Type	Description
`Google\Cloud\Datastore\Query\GqlQuery`

runQuery

See also:

RunQuery API documentation

Parameters
Name	Description
`query`	`Google\Cloud\Datastore\Query\QueryInterface` A query object.
`options`	`array` Configuration Options
`↳ className`	`string` If set, the given class will be returned. Value must be the name of a class implementing Google\Cloud\Datastore\EntityInterface. Defaults to Google\Cloud\Datastore\Entity.
`↳ readConsistency`	`string` See ReadConsistency.
`↳ readTime`	`Timestamp` Reads entities as they were at the given timestamp.

Returns
Type	Description
`Google\Cloud\Datastore\EntityIterator<\google\cloud\datastore\entityinterface>`

runAggregationQuery

See also:

RunAggregationQuery API documentation

Parameters
Name	Description
`query`	`Google\Cloud\Datastore\Query\AggregationQuery` A query object.
`options`	`array` Configuration Options
`↳ readConsistency`	`string` See ReadConsistency.
`↳ readTime`	`Timestamp` Reads entities as they were at the given timestamp.

Returns
Type	Description
`Google\Cloud\Datastore\Query\AggregationQueryResult`

Constants

VERSION

Value: '1.26.0'

FULL_CONTROL_SCOPE

Value: 'https://www.googleapis.com/auth/datastore'