datastore/v1/datastore.proto

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.datastore.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/routing.proto";
import "google/datastore/v1/aggregation_result.proto";
import "google/datastore/v1/entity.proto";
import "google/datastore/v1/query.proto";
import "google/datastore/v1/query_profile.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.Datastore.V1";
option go_package = "google.golang.org/genproto/googleapis/datastore/v1;datastore";
option java_multiple_files = true;
option java_outer_classname = "DatastoreProto";
option java_package = "com.google.datastore.v1";
option php_namespace = "Google\\Cloud\\Datastore\\V1";
option ruby_package = "Google::Cloud::Datastore::V1";

// 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.
//
service Datastore {
  option (google.api.default_host) = "datastore.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/datastore";

  // Looks up entities by key.
  rpc Lookup(LookupRequest) returns (LookupResponse) {
    option (google.api.http) = {
      post: "/v1/projects/{project_id}:lookup"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters { field: "project_id" }
      routing_parameters { field: "database_id" }
    };
    option (google.api.method_signature) = "project_id,read_options,keys";
  }

  // Queries for entities.
  rpc RunQuery(RunQueryRequest) returns (RunQueryResponse) {
    option (google.api.http) = {
      post: "/v1/projects/{project_id}:runQuery"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters { field: "project_id" }
      routing_parameters { field: "database_id" }
    };
  }

  // Runs an aggregation query.
  rpc RunAggregationQuery(RunAggregationQueryRequest)
      returns (RunAggregationQueryResponse) {
    option (google.api.http) = {
      post: "/v1/projects/{project_id}:runAggregationQuery"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters { field: "project_id" }
      routing_parameters { field: "database_id" }
    };
  }

  // Begins a new transaction.
  rpc BeginTransaction(BeginTransactionRequest)
      returns (BeginTransactionResponse) {
    option (google.api.http) = {
      post: "/v1/projects/{project_id}:beginTransaction"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters { field: "project_id" }
      routing_parameters { field: "database_id" }
    };
    option (google.api.method_signature) = "project_id";
  }

  // Commits a transaction, optionally creating, deleting or modifying some
  // entities.
  rpc Commit(CommitRequest) returns (CommitResponse) {
    option (google.api.http) = {
      post: "/v1/projects/{project_id}:commit"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters { field: "project_id" }
      routing_parameters { field: "database_id" }
    };
    option (google.api.method_signature) =
        "project_id,mode,transaction,mutations";
    option (google.api.method_signature) = "project_id,mode,mutations";
  }

  // Rolls back a transaction.
  rpc Rollback(RollbackRequest) returns (RollbackResponse) {
    option (google.api.http) = {
      post: "/v1/projects/{project_id}:rollback"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters { field: "project_id" }
      routing_parameters { field: "database_id" }
    };
    option (google.api.method_signature) = "project_id,transaction";
  }

  // Allocates IDs for the given keys, which is useful for referencing an entity
  // before it is inserted.
  rpc AllocateIds(AllocateIdsRequest) returns (AllocateIdsResponse) {
    option (google.api.http) = {
      post: "/v1/projects/{project_id}:allocateIds"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters { field: "project_id" }
      routing_parameters { field: "database_id" }
    };
    option (google.api.method_signature) = "project_id,keys";
  }

  // Prevents the supplied keys' IDs from being auto-allocated by Cloud
  // Datastore.
  rpc ReserveIds(ReserveIdsRequest) returns (ReserveIdsResponse) {
    option (google.api.http) = {
      post: "/v1/projects/{project_id}:reserveIds"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters { field: "project_id" }
      routing_parameters { field: "database_id" }
    };
    option (google.api.method_signature) = "project_id,keys";
  }
}

// The request for [Datastore.Lookup][google.datastore.v1.Datastore.Lookup].
message LookupRequest {
  // Required. The ID of the project against which to make the request.
  string project_id = 8 [(google.api.field_behavior) = REQUIRED];

  // The ID of the database against which to make the request.
  //
  // '(default)' is not allowed; please use empty string '' to refer the default
  // database.
  string database_id = 9;

  // The options for this lookup request.
  ReadOptions read_options = 1;

  // Required. Keys of entities to look up.
  repeated Key keys = 3 [(google.api.field_behavior) = REQUIRED];
}

// The response for [Datastore.Lookup][google.datastore.v1.Datastore.Lookup].
message LookupResponse {
  // Entities found as `ResultType.FULL` entities. The order of results in this
  // field is undefined and has no relation to the order of the keys in the
  // input.
  repeated EntityResult found = 1;

  // Entities not found as `ResultType.KEY_ONLY` entities. The order of results
  // in this field is undefined and has no relation to the order of the keys
  // in the input.
  repeated EntityResult missing = 2;

  // A list of keys that were not looked up due to resource constraints. The
  // order of results in this field is undefined and has no relation to the
  // order of the keys in the input.
  repeated Key deferred = 3;

  // The identifier of the transaction that was started as part of this Lookup
  // request.
  //
  // Set only when
  // [ReadOptions.new_transaction][google.datastore.v1.ReadOptions.new_transaction]
  // was set in
  // [LookupRequest.read_options][google.datastore.v1.LookupRequest.read_options].
  bytes transaction = 5;

  // The time at which these entities were read or found missing.
  google.protobuf.Timestamp read_time = 7;
}

// The request for [Datastore.RunQuery][google.datastore.v1.Datastore.RunQuery].
message RunQueryRequest {
  // Required. The ID of the project against which to make the request.
  string project_id = 8 [(google.api.field_behavior) = REQUIRED];

  // The ID of the database against which to make the request.
  //
  // '(default)' is not allowed; please use empty string '' to refer the default
  // database.
  string database_id = 9;

  // 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.
  PartitionId partition_id = 2;

  // The options for this query.
  ReadOptions read_options = 1;

  // The type of query.
  oneof query_type {
    // The query to run.
    Query query = 3;

    // The GQL query to run. This query must be a non-aggregation query.
    GqlQuery gql_query = 7;
  }

  // Optional. Explain options for the query. If set, additional query
  // statistics will be returned. If not, only query results will be returned.
  ExplainOptions explain_options = 12 [(google.api.field_behavior) = OPTIONAL];
}

// The response for
// [Datastore.RunQuery][google.datastore.v1.Datastore.RunQuery].
message RunQueryResponse {
  // A batch of query results (always present).
  QueryResultBatch batch = 1;

  // The parsed form of the `GqlQuery` from the request, if it was set.
  Query query = 2;

  // The identifier of the transaction that was started as part of this
  // RunQuery request.
  //
  // Set only when
  // [ReadOptions.new_transaction][google.datastore.v1.ReadOptions.new_transaction]
  // was set in
  // [RunQueryRequest.read_options][google.datastore.v1.RunQueryRequest.read_options].
  bytes transaction = 5;

  // Query explain metrics. This is only present when the
  // [RunQueryRequest.explain_options][google.datastore.v1.RunQueryRequest.explain_options]
  // is provided, and it is sent only once with the last response in the stream.
  ExplainMetrics explain_metrics = 9;
}

// The request for
// [Datastore.RunAggregationQuery][google.datastore.v1.Datastore.RunAggregationQuery].
message RunAggregationQueryRequest {
  // Required. The ID of the project against which to make the request.
  string project_id = 8 [(google.api.field_behavior) = REQUIRED];

  // The ID of the database against which to make the request.
  //
  // '(default)' is not allowed; please use empty string '' to refer the default
  // database.
  string database_id = 9;

  // 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.
  PartitionId partition_id = 2;

  // The options for this query.
  ReadOptions read_options = 1;

  // The type of query.
  oneof query_type {
    // The query to run.
    AggregationQuery aggregation_query = 3;

    // The GQL query to run. This query must be an aggregation query.
    GqlQuery gql_query = 7;
  }

  // Optional. Explain options for the query. If set, additional query
  // statistics will be returned. If not, only query results will be returned.
  ExplainOptions explain_options = 11 [(google.api.field_behavior) = OPTIONAL];
}

// The response for
// [Datastore.RunAggregationQuery][google.datastore.v1.Datastore.RunAggregationQuery].
message RunAggregationQueryResponse {
  // A batch of aggregation results. Always present.
  AggregationResultBatch batch = 1;

  // The parsed form of the `GqlQuery` from the request, if it was set.
  AggregationQuery query = 2;

  // The identifier of the transaction that was started as part of this
  // RunAggregationQuery request.
  //
  // Set only when
  // [ReadOptions.new_transaction][google.datastore.v1.ReadOptions.new_transaction]
  // was set in
  // [RunAggregationQueryRequest.read_options][google.datastore.v1.RunAggregationQueryRequest.read_options].
  bytes transaction = 5;

  // Query explain metrics. This is only present when the
  // [RunAggregationQueryRequest.explain_options][google.datastore.v1.RunAggregationQueryRequest.explain_options]
  // is provided, and it is sent only once with the last response in the stream.
  ExplainMetrics explain_metrics = 9;
}

// The request for
// [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
message BeginTransactionRequest {
  // Required. The ID of the project against which to make the request.
  string project_id = 8 [(google.api.field_behavior) = REQUIRED];

  // The ID of the database against which to make the request.
  //
  // '(default)' is not allowed; please use empty string '' to refer the default
  // database.
  string database_id = 9;

  // Options for a new transaction.
  TransactionOptions transaction_options = 10;
}

// The response for
// [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
message BeginTransactionResponse {
  // The transaction identifier (always present).
  bytes transaction = 1;
}

// The request for [Datastore.Rollback][google.datastore.v1.Datastore.Rollback].
message RollbackRequest {
  // Required. The ID of the project against which to make the request.
  string project_id = 8 [(google.api.field_behavior) = REQUIRED];

  // The ID of the database against which to make the request.
  //
  // '(default)' is not allowed; please use empty string '' to refer the default
  // database.
  string database_id = 9;

  // Required. The transaction identifier, returned by a call to
  // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
  bytes transaction = 1 [(google.api.field_behavior) = REQUIRED];
}

// The response for
// [Datastore.Rollback][google.datastore.v1.Datastore.Rollback]. (an empty
// message).
message RollbackResponse {}

// The request for [Datastore.Commit][google.datastore.v1.Datastore.Commit].
message CommitRequest {
  // The modes available for commits.
  enum Mode {
    // Unspecified. This value must not be used.
    MODE_UNSPECIFIED = 0;

    // Transactional: The mutations are either all applied, or none are applied.
    // Learn about transactions
    // [here](https://cloud.google.com/datastore/docs/concepts/transactions).
    TRANSACTIONAL = 1;

    // Non-transactional: The mutations may not apply as all or none.
    NON_TRANSACTIONAL = 2;
  }

  // Required. The ID of the project against which to make the request.
  string project_id = 8 [(google.api.field_behavior) = REQUIRED];

  // The ID of the database against which to make the request.
  //
  // '(default)' is not allowed; please use empty string '' to refer the default
  // database.
  string database_id = 9;

  // The type of commit to perform. Defaults to `TRANSACTIONAL`.
  Mode mode = 5;

  // Must be set when mode is `TRANSACTIONAL`.
  oneof transaction_selector {
    // The identifier of the transaction associated with the commit. A
    // transaction identifier is returned by a call to
    // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
    bytes transaction = 1;

    // Options for beginning a new transaction for this request.
    // The transaction is committed when the request completes. If specified,
    // [TransactionOptions.mode][google.datastore.v1.TransactionOptions] must be
    // [TransactionOptions.ReadWrite][google.datastore.v1.TransactionOptions.ReadWrite].
    TransactionOptions single_use_transaction = 10;
  }

  // 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.
  repeated Mutation mutations = 6;
}

// The response for [Datastore.Commit][google.datastore.v1.Datastore.Commit].
message CommitResponse {
  // The result of performing the mutations.
  // The i-th mutation result corresponds to the i-th mutation in the request.
  repeated MutationResult mutation_results = 3;

  // The number of index entries updated during the commit, or zero if none were
  // updated.
  int32 index_updates = 4;

  // The transaction commit timestamp. Not set for non-transactional commits.
  google.protobuf.Timestamp commit_time = 8;
}

// The request for
// [Datastore.AllocateIds][google.datastore.v1.Datastore.AllocateIds].
message AllocateIdsRequest {
  // Required. The ID of the project against which to make the request.
  string project_id = 8 [(google.api.field_behavior) = REQUIRED];

  // The ID of the database against which to make the request.
  //
  // '(default)' is not allowed; please use empty string '' to refer the default
  // database.
  string database_id = 9;

  // Required. A list of keys with incomplete key paths for which to allocate
  // IDs. No key may be reserved/read-only.
  repeated Key keys = 1 [(google.api.field_behavior) = REQUIRED];
}

// The response for
// [Datastore.AllocateIds][google.datastore.v1.Datastore.AllocateIds].
message AllocateIdsResponse {
  // The keys specified in the request (in the same order), each with
  // its key path completed with a newly allocated ID.
  repeated Key keys = 1;
}

// The request for
// [Datastore.ReserveIds][google.datastore.v1.Datastore.ReserveIds].
message ReserveIdsRequest {
  // Required. The ID of the project against which to make the request.
  string project_id = 8 [(google.api.field_behavior) = REQUIRED];

  // The ID of the database against which to make the request.
  //
  // '(default)' is not allowed; please use empty string '' to refer the default
  // database.
  string database_id = 9;

  // Required. A list of keys with complete key paths whose numeric IDs should
  // not be auto-allocated.
  repeated Key keys = 1 [(google.api.field_behavior) = REQUIRED];
}

// The response for
// [Datastore.ReserveIds][google.datastore.v1.Datastore.ReserveIds].
message ReserveIdsResponse {}

// A mutation to apply to an entity.
message Mutation {
  // The mutation operation.
  //
  // For `insert`, `update`, and `upsert`:
  // - The entity's key must not be reserved/read-only.
  // - No property in the entity may have a reserved name,
  //   not even a property in an entity in a value.
  // - No value in the entity may have meaning 18,
  //   not even a value in an entity in another value.
  oneof operation {
    // The entity to insert. The entity must not already exist.
    // The entity key's final path element may be incomplete.
    Entity insert = 4;

    // The entity to update. The entity must already exist.
    // Must have a complete key path.
    Entity update = 5;

    // The entity to upsert. The entity may or may not already exist.
    // The entity key's final path element may be incomplete.
    Entity upsert = 6;

    // The key of the entity to delete. The entity may or may not already exist.
    // Must have a complete key path and must not be reserved/read-only.
    Key delete = 7;
  }

  // When set, the server will detect whether or not this mutation conflicts
  // with the current version of the entity on the server. Conflicting mutations
  // are not applied, and are marked as such in MutationResult.
  oneof conflict_detection_strategy {
    // 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.
    int64 base_version = 8;

    // The update time of the entity that this mutation is being applied
    // to. If this does not match the current update time on the server, the
    // mutation conflicts.
    google.protobuf.Timestamp update_time = 11;
  }
}

// The result of applying a mutation.
message MutationResult {
  // The automatically allocated key.
  // Set only when the mutation allocated a key.
  Key key = 3;

  // The version of the entity on the server after processing the mutation. If
  // the mutation doesn't change anything on the server, then the version will
  // be the version of the current entity or, if no entity is present, a version
  // that is strictly greater than the version of any previous entity and less
  // than the version of any possible future entity.
  int64 version = 4;

  // The create time of the entity. This field will not be set after a 'delete'.
  google.protobuf.Timestamp create_time = 7;

  // The update time of the entity on the server after processing the mutation.
  // If the mutation doesn't change anything on the server, then the timestamp
  // will be the update timestamp of the current entity. This field will not be
  // set after a 'delete'.
  google.protobuf.Timestamp update_time = 6;

  // Whether a conflict was detected for this mutation. Always false when a
  // conflict detection strategy field is not set in the mutation.
  bool conflict_detected = 5;
}

// The options shared by read requests.
message ReadOptions {
  // The possible values for read consistencies.
  enum ReadConsistency {
    // Unspecified. This value must not be used.
    READ_CONSISTENCY_UNSPECIFIED = 0;

    // Strong consistency.
    STRONG = 1;

    // Eventual consistency.
    EVENTUAL = 2;
  }

  // For Cloud Datastore, if read_consistency is not specified, then lookups and
  // ancestor queries default to `read_consistency`=`STRONG`, global queries
  // default to `read_consistency`=`EVENTUAL`.
  //
  // For Cloud Firestore in Datastore mode, if read_consistency is not specified
  // then lookups and all queries default to `read_consistency`=`STRONG`.
  //
  // Explicitly setting `read_consistency`=`EVENTUAL` will result in eventually
  // consistent lookups & queries in both Cloud Datastore & Cloud Firestore in
  // Datastore mode.
  oneof consistency_type {
    // The non-transactional read consistency to use.
    ReadConsistency read_consistency = 1;

    // The identifier of the transaction in which to read. A
    // transaction identifier is returned by a call to
    // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
    bytes transaction = 2;

    // Options for beginning a new transaction for this request.
    //
    // The new transaction identifier will be returned in the corresponding
    // response as either
    // [LookupResponse.transaction][google.datastore.v1.LookupResponse.transaction]
    // or
    // [RunQueryResponse.transaction][google.datastore.v1.RunQueryResponse.transaction].
    TransactionOptions new_transaction = 3;

    // Reads entities as they were at the given time. This value is only
    // supported for Cloud Firestore in Datastore mode.
    //
    // This must be a microsecond precision timestamp within the past one hour,
    // or if Point-in-Time Recovery is enabled, can additionally be a whole
    // minute timestamp within the past 7 days.
    google.protobuf.Timestamp read_time = 4;
  }
}

// Options for beginning a new transaction.
//
// Transactions can be created explicitly with calls to
// [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction]
// or implicitly by setting
// [ReadOptions.new_transaction][google.datastore.v1.ReadOptions.new_transaction]
// in read requests.
message TransactionOptions {
  // Options specific to read / write transactions.
  message ReadWrite {
    // The transaction identifier of the transaction being retried.
    bytes previous_transaction = 1;
  }

  // Options specific to read-only transactions.
  message ReadOnly {
    // Reads entities at the given time.
    //
    // This must be a microsecond precision timestamp within the past one hour,
    // or if Point-in-Time Recovery is enabled, can additionally be a whole
    // minute timestamp within the past 7 days.
    google.protobuf.Timestamp read_time = 1;
  }

  // The `mode` of the transaction, indicating whether write operations are
  // supported.
  oneof mode {
    // The transaction should allow both reads and writes.
    ReadWrite read_write = 1;

    // The transaction should only allow reads.
    ReadOnly read_only = 2;
  }
}