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.
config
↳ projectId
string
The project ID from the Google Developer's Console.
↳ namespaceId
↳ 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 tofalse.
↳ datastoreClient
↳ apiEndpoint
string
The address of the API remote host. May optionally include the port, formatted as "
↳ credentials
FetchAuthTokenInterface|CredentialsWrapper
This option should only be used with a pre-constructed Google\Auth\FetchAuthTokenInterface
or Google\ApiCore\CredentialsWrapper
object. Note that when one of these objects are provided, any settings in $credentialsConfig will be ignored. Important: If you are providing a path to a credentials file, or a decoded credentials file as a PHP array, this usage is now DEPRECATED. Providing an unvalidated credential configuration to Google APIs can compromise the security of your systems and data. It is recommended to create the credentials explicitly use Google\Auth\Credentials\ServiceAccountCredentials; use Google\Cloud\Datastore\V1\DatastoreClient; $creds = new ServiceAccountCredentials($scopes, $json); $options = new DatastoreClient(['credentials' => $creds]);
https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
↳ credentialsConfig
array
Options used to configure credentials, including auth token caching, for the client. For a full list of supporting configuration options, see Google\ApiCore\CredentialsWrapper::build() .
↳ disableRetries
bool
Determines whether or not retries defined by the client configuration should be disabled. Defaults to false
.
↳ clientConfig
string|array
Client method configuration, including retry settings. This option can be either a path to a JSON file, or a PHP array containing the decoded JSON data. By default this settings points to the default client config file, which is provided in the resources folder.
↳ transport
string|TransportInterface
The transport used for executing network requests. May be either the string rest
or grpc
. Defaults to grpc
if gRPC support is detected on the system. Advanced usage
: Additionally, it is possible to pass in an already instantiated Google\ApiCore\Transport\TransportInterface
object. Note that when this object is provided, any settings in $transportConfig, and any $apiEndpoint setting, will be ignored.
↳ transportConfig
array
Configuration options that will be used to construct the transport. Options for each supported transport type should be passed in a key for that transport. For example: $transportConfig = [ 'grpc' => [...], 'rest' => [...], ]; See the Google\ApiCore\Transport\GrpcTransport::build() and Google\ApiCore\Transport\RestTransport::build() methods for the supported options.
↳ clientCertSource
callable
A callable which returns the client cert as a string. This can be used to provide a certificate and private key to the transport layer for mTLS.
↳ logger
false|LoggerInterface
A PSR-3 compliant logger. If set to false, logging is disabled, ignoring the 'GOOGLE_SDK_PHP_LOGGING' environment flag
↳ universeDomain
string
The service domain for the client. Defaults to 'googleapis.com'.
key
See also:
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
.
keys
See also:
kind
string
The kind to use in the final path element.
options
array
Configuration Options
↳ ancestors
↳ 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.
entity
See also:
key
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 EntityInterface . Defaults to Entity .
↳ excludeFromIndexes
array
A list of entity keys to exclude from datastore indexes.
EntityInterface
geoPoint
See also:
latitude
float
The latitude
longitude
float
The longitude
allowNull
bool
[optional] Whether null values are allowed. Defaults to
* false
.
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'));
value
string|resource| Psr\Http\Message\StreamInterface
The value to store in a 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');
value
string
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);
cursorValue
string|int
allocateId
See also:
key
options
array
[optional] Configuration options.
allocateIds
See also:
keys
options
array
Configuration Options.
string $databaseId The ID of the database against which to make the request.
}
transaction
See also:
options
array
Configuration options.
↳ transactionOptions
↳ databaseId
string
ID of the database to which the entities belong.
readOnlyTransaction
See also:
options
array
Configuration options.
↳ transactionOptions
↳ databaseId
string
ID of the database to which the entities belong.
insert
See also:
entity
EntityInterface
The entity to be inserted.
options
array
[optional] Configuration options.
string
insertBatch
See also:
entities
array< EntityInterface
>
The entities to be inserted.
options
array
[optional] Configuration options.
array
update
See also:
entity
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
.
string
updateBatch
See also:
entities
array< 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
.
array
upsert
See also:
entity
EntityInterface
The entity to be upserted.
options
array
[optional] Configuration Options.
string
upsertBatch
See also:
entities
array< EntityInterface
>
The entities to be upserted.
options
array
[optional] Configuration Options.
array
delete
See also:
key
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.
string
deleteBatch
See also:
keys
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.
array
lookup
See also:
key
options
array
Configuration Options
↳ readConsistency
↳ className
string
If set, the given class will be returned. Value must be the name of a class implementing EntityInterface . Defaults to Entity .
↳ databaseId
string
ID of the database to which the entities belong.
↳ readTime
Timestamp
Reads entities as they were at the given timestamp.
EntityInterface
|null
lookupBatch
See also:
keys
options
array
Configuration Options
↳ readConsistency
↳ className
string|array
If a string, the given class will be returned. Value must be the name of a class implementing EntityInterface . If an array is given, it must be an associative array, where the key is a Kind and the value must implement EntityInterface . Defaults to 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.
array
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();
aggregationQuery
Create an AggregationQuery object.
In addition to Query features, it supports aggregations.
Example:
$query = $datastore->aggregationQuery();
gqlQuery
Create a GqlQuery object.
Returns a Query object which can be executed using 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
]
]);
query
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 Cursor .
↳ readConsistency
runQuery
See also:
query
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 EntityInterface . Defaults to Entity .
↳ readConsistency
↳ readTime
Timestamp
Reads entities as they were at the given timestamp.
runAggregationQuery
See also:
query
options
array
Configuration Options
↳ readConsistency
↳ readTime
Timestamp
Reads entities as they were at the given timestamp.
↳ explainOptions
ExplainOptions
An ExplainOptions instance. V1\ExplainOptions} </xref
Constants
VERSION
Value: '2.0.0-RC1'
FULL_CONTROL_SCOPE
Value: 'https://www.googleapis.com/auth/datastore'
