Cloud Datastore Client - Class DatastoreClient (1.17.1)

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'
]);

Create a Datastore client.

Create a single Key instance

Example:

$key = $datastore->key('Person', 'Bob');

// To override the internal detection of identifier type, you can specify
// which type to use.

$key = $datastore->key('Robots', '1337', [
    'identifierType' => Key::TYPE_NAME
]);

Create multiple keys with the same configuration.

When inserting multiple entities, creating a set of keys at once can be useful. By defining the Key's kind and any ancestors up front, and allowing Cloud Datastore to allocate IDs, you can be sure that your entity identity and ancestry are correct and that there will be no collisions during the insert operation.

Example:

$keys = $datastore->keys('Person', [
    'number' => 10
]);

// Ancestor paths can be specified
$keys = $datastore->keys('Person', [
    'ancestors' => [
        ['kind' => 'Person', 'name' => 'Grandpa Joe'],
        ['kind' => 'Person', 'name' => 'Dad Mike']
    ],
    'number' => 3
]);

Create an entity.

This method does not execute any service requests.

Entities are created with a Datastore Key, or by specifying a Kind. Kinds are only allowed for insert operations. For any other case, you must specify a named key. If a kind is given, an ID will be automatically allocated for the entity upon insert. Additionally, if your entity requires a complex key elementPath, you must create the key separately.

In complex applications you may want to create your own entity types. Google Cloud PHP supports subclassing of {@see}. If the name of a subclass of Entity is given in the options array, an entity will be created with that class rather than the default class.

Example:

$key = $datastore->key('Person', 'Bob');
$entity = $datastore->entity($key, [
    'firstName' => 'Bob',
    'lastName' => 'Testguy'
]);

// Entity values can be assigned and accessed via the array syntax.
$entity = $datastore->entity($key);

$entity['firstName'] = 'Bob';
$entity['lastName'] = 'Testguy';

// Entity values can also be assigned and accessed via an object syntax.
$entity = $datastore->entity($key);

$entity->firstName = 'Bob';
$entity->lastName = 'Testguy';

// Entities can be created with a Kind only, for inserting into datastore
$entity = $datastore->entity('Person');

// Entities can be custom classes implementing the Datastore entity interface.
use Google\Cloud\Datastore\EntityTrait;
use Google\Cloud\Datastore\EntityInterface;

class PersonEntity implements EntityInterface
{
    use EntityTrait;
}

$person = $datastore->entity('Person', [ 'firstName' => 'Bob'], [
    'className' => PersonEntity::class
]);

echo get_class($person); // `Person`

// Custom entity types may also extend the built-in Entity class.
use Google\Cloud\Datastore\Entity;

class OtherPersonEntity extends Entity
}

$person = $datastore->entity('Person', [ 'firstName' => 'Bob'], [
    'className' => OtherPersonEntity::class
]);

echo get_class($person); // `Person`

// If you wish to exclude certain properties from datastore indexes,
// property names may be supplied in the method $options:

$entity = $datastore->entity('Person', [
    'firstName' => 'Bob',
    'dateOfBirth' => new DateTime('January 31, 1969')
], [
    'excludeFromIndexes' => [
        'dateOfBirth'
    ]
]);

Create a new GeoPoint

Example:

$geoPoint = $datastore->geoPoint(37.4220, -122.0841);

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'));

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');

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);

Allocates an available ID to a given incomplete key

Key MUST be in an incomplete state (i.e. including a kind but not an ID or name in its final pathElement).

This method will execute a service request.

Example:

$key = $datastore->key('Person');
$keyWithAllocatedId = $datastore->allocateId($key);

Allocate available IDs to a set of keys

Keys MUST be in an incomplete state (i.e. including a kind but not an ID or name in their final pathElement).

This method will execute a service request.

Example:

$keys = [
    $datastore->key('Person'),
    $datastore->key('Person')
];

$keysWithAllocatedIds = $datastore->allocateIds($keys);

Create a Transaction.

Example:

$transaction = $datastore->transaction();

Create a Read-Only Transaction.

Example:

$transaction = $datastore->readOnlyTransaction();

Insert an entity

An entity with incomplete keys will be allocated an ID prior to insertion.

Insert by this method is non-transactional. If you need transaction support, use {@see}.

Example:

$key = $datastore->key('Person', 'Bob');
$entity = $datastore->entity($key, ['firstName' => 'Bob']);

$datastore->insert($entity);

Insert multiple entities

Any entity with incomplete keys will be allocated an ID prior to insertion.

Insert by this method is non-transactional. If you need transaction support, use {@see}.

Example:

$entities = [
    $datastore->entity('Person', ['firstName' => 'Bob']),
    $datastore->entity('Person', ['firstName' => 'John'])
];

$datastore->insertBatch($entities);

Update an entity

Please note that updating a record in Cloud Datastore will replace the existing record. Adding, editing or removing a single property is only possible by first retrieving the entire entity in its existing state.

Update by this method is non-transactional. If you need transaction support, use {@see}.

Example:

$entity['firstName'] = 'John';

$datastore->update($entity);

Update multiple entities

Please note that updating a record in Cloud Datastore will replace the existing record. Adding, editing or removing a single property is only possible by first retrieving the entire entity in its existing state.

Update by this method is non-transactional. If you need transaction support, use {@see}.

Example:

$entities[0]['firstName'] = 'Bob';
$entities[1]['firstName'] = 'John';

$datastore->updateBatch($entities);

Upsert an entity

Upsert will create a record if one does not already exist, or overwrite existing record if one already exists.

Please note that upserting a record in Cloud Datastore will replace the existing record, if one exists. Adding, editing or removing a single property is only possible by first retrieving the entire entity in its existing state.

An entity with incomplete keys will be allocated an ID prior to insertion.

Upsert by this method is non-transactional. If you need transaction support, use {@see}.

Example:

$key = $datastore->key('Person', 'Bob');
$entity = $datastore->entity($key, ['firstName' => 'Bob']);

$datastore->upsert($entity);

Upsert multiple entities

Upsert will create a record if one does not already exist, or overwrite an existing record if one already exists.

Please note that upserting a record in Cloud Datastore will replace the existing record, if one exists. Adding, editing or removing a single property is only possible by first retrieving the entire entity in its existing state.

Any entity with incomplete keys will be allocated an ID prior to insertion.

Upsert by this method is non-transactional. If you need transaction support, use {@see}.

Example:

$keys = [
    $datastore->key('Person', 'Bob'),
    $datastore->key('Person', 'John')
];

$entities = [
    $datastore->entity($keys[0], ['firstName' => 'Bob']),
    $datastore->entity($keys[1], ['firstName' => 'John'])
];

$datastore->upsertBatch($entities);

Delete an entity

Deletion by this method is non-transactional. If you need transaction support, use {@see}.

Example:

$key = $datastore->key('Person', 'Bob');

$datastore->delete($key);

Delete multiple entities

Deletion by this method is non-transactional. If you need transaction support, use {@see}.

Example:

$keys = [
    $datastore->key('Person', 'Bob'),
    $datastore->key('Person', 'John')
];

$datastore->deleteBatch($keys);

Retrieve an entity from the datastore

To lookup an entity inside a transaction, use {@see}.

Example:

$key = $datastore->key('Person', 'Bob');

$entity = $datastore->lookup($key);
if (!is_null($entity)) {
    echo $entity['firstName']; // 'Bob'
}

Get multiple entities

To lookup entities inside a transaction, use {@see}.

Example:

$keys = [
    $datastore->key('Person', 'Bob'),
    $datastore->key('Person', 'John')
];

$entities = $datastore->lookupBatch($keys);

foreach ($entities['found'] as $entity) {
    echo $entity['firstName'] . PHP_EOL;
}

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();

Create a GqlQuery object.

Returns a Query object which can be executed using {@see}.

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
    ]
]);

Run a query and return entities

To query datastore inside a transaction, use {@see}.

Example:

$result = $datastore->runQuery($query);

foreach ($result as $entity) {
    echo $entity['firstName'];
}