Cloud Datastore Client - Class DatastoreClient (1.31.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:

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:

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:

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.31.0'

FULL_CONTROL_SCOPE

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