Firestore in Datastore mode V1 API - Class Google::Cloud::Datastore::V1::Datastore::Client (v0.15.0)

Reference documentation and code samples for the Firestore in Datastore mode V1 API class Google::Cloud::Datastore::V1::Datastore::Client.

Client for the Datastore service.

Each RPC normalizes the partition IDs of the keys in its input entities, and always returns entities with keys with normalized partition IDs. This applies to all keys and entities, including those in values, except keys with both an empty path and an empty or unset partition ID. Normalization of input keys sets the project ID (if not already set) to the project ID from the request.

Inherits

  • Object

Methods

.configure

def self.configure() { |config| ... } -> Client::Configuration

Configure the Datastore Client class.

See Configuration for a description of the configuration fields.

Yields
  • (config) — Configure the Client client.
Yield Parameter
Returns
Example 
# Modify the configuration for all Datastore clients
::Google::Cloud::Datastore::V1::Datastore::Client.configure do |config|
  config.timeout = 10.0
end

#allocate_ids

def allocate_ids(request, options = nil) -> ::Google::Cloud::Datastore::V1::AllocateIdsResponse
def allocate_ids(project_id: nil, database_id: nil, keys: nil) -> ::Google::Cloud::Datastore::V1::AllocateIdsResponse

Allocates IDs for the given keys, which is useful for referencing an entity before it is inserted.

Overloads 
def allocate_ids(request, options = nil) -> ::Google::Cloud::Datastore::V1::AllocateIdsResponse
Pass arguments to allocate_ids via a request object, either of type AllocateIdsRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Datastore::V1::AllocateIdsRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def allocate_ids(project_id: nil, database_id: nil, keys: nil) -> ::Google::Cloud::Datastore::V1::AllocateIdsResponse
Pass arguments to allocate_ids via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • project_id (::String) — Required. The ID of the project against which to make the request.
  • database_id (::String) — The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

  • keys (::Array<::Google::Cloud::Datastore::V1::Key, ::Hash>) — Required. A list of keys with incomplete key paths for which to allocate IDs. No key may be reserved/read-only.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/datastore/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Datastore::V1::AllocateIdsRequest.new

# Call the allocate_ids method.
result = client.allocate_ids request

# The returned object is of type Google::Cloud::Datastore::V1::AllocateIdsResponse.
p result

#begin_transaction

def begin_transaction(request, options = nil) -> ::Google::Cloud::Datastore::V1::BeginTransactionResponse
def begin_transaction(project_id: nil, database_id: nil, transaction_options: nil) -> ::Google::Cloud::Datastore::V1::BeginTransactionResponse

Begins a new transaction.

Overloads 
def begin_transaction(request, options = nil) -> ::Google::Cloud::Datastore::V1::BeginTransactionResponse
Pass arguments to begin_transaction via a request object, either of type BeginTransactionRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Datastore::V1::BeginTransactionRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def begin_transaction(project_id: nil, database_id: nil, transaction_options: nil) -> ::Google::Cloud::Datastore::V1::BeginTransactionResponse
Pass arguments to begin_transaction via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • project_id (::String) — Required. The ID of the project against which to make the request.
  • database_id (::String) — The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

  • transaction_options (::Google::Cloud::Datastore::V1::TransactionOptions, ::Hash) — Options for a new transaction.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/datastore/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Datastore::V1::BeginTransactionRequest.new

# Call the begin_transaction method.
result = client.begin_transaction request

# The returned object is of type Google::Cloud::Datastore::V1::BeginTransactionResponse.
p result

#commit

def commit(request, options = nil) -> ::Google::Cloud::Datastore::V1::CommitResponse
def commit(project_id: nil, database_id: nil, mode: nil, transaction: nil, single_use_transaction: nil, mutations: nil) -> ::Google::Cloud::Datastore::V1::CommitResponse

Commits a transaction, optionally creating, deleting or modifying some entities.

Overloads 
def commit(request, options = nil) -> ::Google::Cloud::Datastore::V1::CommitResponse
Pass arguments to commit via a request object, either of type CommitRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Datastore::V1::CommitRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def commit(project_id: nil, database_id: nil, mode: nil, transaction: nil, single_use_transaction: nil, mutations: nil) -> ::Google::Cloud::Datastore::V1::CommitResponse
Pass arguments to commit via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • project_id (::String) — Required. The ID of the project against which to make the request.
  • database_id (::String) — The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

  • mode (::Google::Cloud::Datastore::V1::CommitRequest::Mode) — The type of commit to perform. Defaults to TRANSACTIONAL.
  • transaction (::String) — The identifier of the transaction associated with the commit. A transaction identifier is returned by a call to Datastore.BeginTransaction.
  • single_use_transaction (::Google::Cloud::Datastore::V1::TransactionOptions, ::Hash) — Options for beginning a new transaction for this request. The transaction is committed when the request completes. If specified, TransactionOptions.mode must be TransactionOptions.ReadWrite.
  • mutations (::Array<::Google::Cloud::Datastore::V1::Mutation, ::Hash>) — The mutations to perform.

    When mode is TRANSACTIONAL, mutations affecting a single entity are applied in order. The following sequences of mutations affecting a single entity are not permitted in a single Commit request:

    • insert followed by insert
    • update followed by insert
    • upsert followed by insert
    • delete followed by update

    When mode is NON_TRANSACTIONAL, no two mutations may affect a single entity.

Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/datastore/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Datastore::V1::CommitRequest.new

# Call the commit method.
result = client.commit request

# The returned object is of type Google::Cloud::Datastore::V1::CommitResponse.
p result

#configure

def configure() { |config| ... } -> Client::Configuration

Configure the Datastore Client instance.

The configuration is set to the derived mode, meaning that values can be changed, but structural changes (adding new fields, etc.) are not allowed. Structural changes should be made on Client.configure.

See Configuration for a description of the configuration fields.

Yields
  • (config) — Configure the Client client.
Yield Parameter
Returns

#initialize

def initialize() { |config| ... } -> Client

Create a new Datastore client object.

Yields
  • (config) — Configure the Datastore client.
Yield Parameter
Returns
  • (Client) — a new instance of Client
Example 
# Create a client using the default configuration
client = ::Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a client using a custom configuration
client = ::Google::Cloud::Datastore::V1::Datastore::Client.new do |config|
  config.timeout = 10.0
end

#lookup

def lookup(request, options = nil) -> ::Google::Cloud::Datastore::V1::LookupResponse
def lookup(project_id: nil, database_id: nil, read_options: nil, keys: nil) -> ::Google::Cloud::Datastore::V1::LookupResponse

Looks up entities by key.

Overloads 
def lookup(request, options = nil) -> ::Google::Cloud::Datastore::V1::LookupResponse
Pass arguments to lookup via a request object, either of type LookupRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Datastore::V1::LookupRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def lookup(project_id: nil, database_id: nil, read_options: nil, keys: nil) -> ::Google::Cloud::Datastore::V1::LookupResponse
Pass arguments to lookup via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • project_id (::String) — Required. The ID of the project against which to make the request.
  • database_id (::String) — The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

  • read_options (::Google::Cloud::Datastore::V1::ReadOptions, ::Hash) — The options for this lookup request.
  • keys (::Array<::Google::Cloud::Datastore::V1::Key, ::Hash>) — Required. Keys of entities to look up.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/datastore/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Datastore::V1::LookupRequest.new

# Call the lookup method.
result = client.lookup request

# The returned object is of type Google::Cloud::Datastore::V1::LookupResponse.
p result

#reserve_ids

def reserve_ids(request, options = nil) -> ::Google::Cloud::Datastore::V1::ReserveIdsResponse
def reserve_ids(project_id: nil, database_id: nil, keys: nil) -> ::Google::Cloud::Datastore::V1::ReserveIdsResponse

Prevents the supplied keys' IDs from being auto-allocated by Cloud Datastore.

Overloads 
def reserve_ids(request, options = nil) -> ::Google::Cloud::Datastore::V1::ReserveIdsResponse
Pass arguments to reserve_ids via a request object, either of type ReserveIdsRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Datastore::V1::ReserveIdsRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def reserve_ids(project_id: nil, database_id: nil, keys: nil) -> ::Google::Cloud::Datastore::V1::ReserveIdsResponse
Pass arguments to reserve_ids via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • project_id (::String) — Required. The ID of the project against which to make the request.
  • database_id (::String) — The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

  • keys (::Array<::Google::Cloud::Datastore::V1::Key, ::Hash>) — Required. A list of keys with complete key paths whose numeric IDs should not be auto-allocated.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/datastore/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Datastore::V1::ReserveIdsRequest.new

# Call the reserve_ids method.
result = client.reserve_ids request

# The returned object is of type Google::Cloud::Datastore::V1::ReserveIdsResponse.
p result

#rollback

def rollback(request, options = nil) -> ::Google::Cloud::Datastore::V1::RollbackResponse
def rollback(project_id: nil, database_id: nil, transaction: nil) -> ::Google::Cloud::Datastore::V1::RollbackResponse

Rolls back a transaction.

Overloads 
def rollback(request, options = nil) -> ::Google::Cloud::Datastore::V1::RollbackResponse
Pass arguments to rollback via a request object, either of type RollbackRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Datastore::V1::RollbackRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def rollback(project_id: nil, database_id: nil, transaction: nil) -> ::Google::Cloud::Datastore::V1::RollbackResponse
Pass arguments to rollback via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • project_id (::String) — Required. The ID of the project against which to make the request.
  • database_id (::String) — The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

  • transaction (::String) — Required. The transaction identifier, returned by a call to Datastore.BeginTransaction.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/datastore/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Datastore::V1::RollbackRequest.new

# Call the rollback method.
result = client.rollback request

# The returned object is of type Google::Cloud::Datastore::V1::RollbackResponse.
p result

#run_aggregation_query

def run_aggregation_query(request, options = nil) -> ::Google::Cloud::Datastore::V1::RunAggregationQueryResponse
def run_aggregation_query(project_id: nil, database_id: nil, partition_id: nil, read_options: nil, aggregation_query: nil, gql_query: nil, mode: nil) -> ::Google::Cloud::Datastore::V1::RunAggregationQueryResponse

Runs an aggregation query.

Overloads 
def run_aggregation_query(request, options = nil) -> ::Google::Cloud::Datastore::V1::RunAggregationQueryResponse
Pass arguments to run_aggregation_query via a request object, either of type RunAggregationQueryRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Datastore::V1::RunAggregationQueryRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def run_aggregation_query(project_id: nil, database_id: nil, partition_id: nil, read_options: nil, aggregation_query: nil, gql_query: nil, mode: nil) -> ::Google::Cloud::Datastore::V1::RunAggregationQueryResponse
Pass arguments to run_aggregation_query via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • project_id (::String) — Required. The ID of the project against which to make the request.
  • database_id (::String) — The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

  • partition_id (::Google::Cloud::Datastore::V1::PartitionId, ::Hash) — Entities are partitioned into subsets, identified by a partition ID. Queries are scoped to a single partition. This partition ID is normalized with the standard default context partition ID.
  • read_options (::Google::Cloud::Datastore::V1::ReadOptions, ::Hash) — The options for this query.
  • aggregation_query (::Google::Cloud::Datastore::V1::AggregationQuery, ::Hash) — The query to run.
  • gql_query (::Google::Cloud::Datastore::V1::GqlQuery, ::Hash) — The GQL query to run. This query must be an aggregation query.
  • mode (::Google::Cloud::Datastore::V1::QueryMode) — Optional. The mode in which the query request is processed. This field is optional, and when not provided, it defaults to NORMAL mode where no additional statistics will be returned with the query results.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/datastore/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Datastore::V1::RunAggregationQueryRequest.new

# Call the run_aggregation_query method.
result = client.run_aggregation_query request

# The returned object is of type Google::Cloud::Datastore::V1::RunAggregationQueryResponse.
p result

#run_query

def run_query(request, options = nil) -> ::Google::Cloud::Datastore::V1::RunQueryResponse
def run_query(project_id: nil, database_id: nil, partition_id: nil, read_options: nil, query: nil, gql_query: nil, mode: nil) -> ::Google::Cloud::Datastore::V1::RunQueryResponse

Queries for entities.

Overloads 
def run_query(request, options = nil) -> ::Google::Cloud::Datastore::V1::RunQueryResponse
Pass arguments to run_query via a request object, either of type RunQueryRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Datastore::V1::RunQueryRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def run_query(project_id: nil, database_id: nil, partition_id: nil, read_options: nil, query: nil, gql_query: nil, mode: nil) -> ::Google::Cloud::Datastore::V1::RunQueryResponse
Pass arguments to run_query via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • project_id (::String) — Required. The ID of the project against which to make the request.
  • database_id (::String) — The ID of the database against which to make the request.

    '(default)' is not allowed; please use empty string '' to refer the default database.

  • partition_id (::Google::Cloud::Datastore::V1::PartitionId, ::Hash) — Entities are partitioned into subsets, identified by a partition ID. Queries are scoped to a single partition. This partition ID is normalized with the standard default context partition ID.
  • read_options (::Google::Cloud::Datastore::V1::ReadOptions, ::Hash) — The options for this query.
  • query (::Google::Cloud::Datastore::V1::Query, ::Hash) — The query to run.
  • gql_query (::Google::Cloud::Datastore::V1::GqlQuery, ::Hash) — The GQL query to run. This query must be a non-aggregation query.
  • mode (::Google::Cloud::Datastore::V1::QueryMode) — Optional. The mode in which the query request is processed. This field is optional, and when not provided, it defaults to NORMAL mode where no additional statistics will be returned with the query results.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/datastore/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Datastore::V1::Datastore::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Datastore::V1::RunQueryRequest.new

# Call the run_query method.
result = client.run_query request

# The returned object is of type Google::Cloud::Datastore::V1::RunQueryResponse.
p result