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 \ DatastoreMethods
__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: |
↳ 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 |
↳ retries |
int
Number of retries for a failed request. Defaults to |
↳ 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 |
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 |
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 |
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
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:
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:
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:
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 |
Returns | |
---|---|
Type | Description |
string |
The entity version. |
updateBatch
See also:
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 |
Returns | |
---|---|
Type | Description |
array |
[Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body) |
upsert
See also:
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:
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:
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:
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:
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:
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 |
↳ 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
|
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
|
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 |
↳ 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:
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:
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'