google-cloud-datastore 0.21.0 → 0.23.0

data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/entity.rb

@@ -0,0 +1,187 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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.
+
+module Google
+  module Datastore
+    module V1
+      # A partition ID identifies a grouping of entities. The grouping is always
+      # by project and namespace, however the namespace ID may be empty.
+      #
+      # A partition ID contains several dimensions:
+      # project ID and namespace ID.
+      #
+      # Partition dimensions:
+      #
+      # - May be +""+.
+      # - Must be valid UTF-8 bytes.
+      # - Must have values that match regex +[A-Za-z\d\.\-_]{1,100}+
+      # If the value of any dimension matches regex +__.*__+, the partition is
+      # reserved/read-only.
+      # A reserved/read-only partition ID is forbidden in certain documented
+      # contexts.
+      #
+      # Foreign partition IDs (in which the project ID does
+      # not match the context project ID ) are discouraged.
+      # Reads and writes of foreign partition IDs may fail if the project is not in an active state.
+      # @!attribute [rw] project_id
+      #   @return [String]
+      #     The ID of the project to which the entities belong.
+      # @!attribute [rw] namespace_id
+      #   @return [String]
+      #     If not empty, the ID of the namespace to which the entities belong.
+      class PartitionId; end
+
+      # A unique identifier for an entity.
+      # If a key's partition ID or any of its path kinds or names are
+      # reserved/read-only, the key is reserved/read-only.
+      # A reserved/read-only key is forbidden in certain documented contexts.
+      # @!attribute [rw] partition_id
+      #   @return [Google::Datastore::V1::PartitionId]
+      #     Entities are partitioned into subsets, currently identified by a project
+      #     ID and namespace ID.
+      #     Queries are scoped to a single partition.
+      # @!attribute [rw] path
+      #   @return [Array<Google::Datastore::V1::Key::PathElement>]
+      #     The entity path.
+      #     An entity path consists of one or more elements composed of a kind and a
+      #     string or numerical identifier, which identify entities. The first
+      #     element identifies a _root entity_, the second element identifies
+      #     a _child_ of the root entity, the third element identifies a child of the
+      #     second entity, and so forth. The entities identified by all prefixes of
+      #     the path are called the element's _ancestors_.
+      #
+      #     An entity path is always fully complete: *all* of the entity's ancestors
+      #     are required to be in the path along with the entity identifier itself.
+      #     The only exception is that in some documented cases, the identifier in the
+      #     last path element (for the entity) itself may be omitted. For example,
+      #     the last path element of the key of +Mutation.insert+ may have no
+      #     identifier.
+      #
+      #     A path can never be empty, and a path can have at most 100 elements.
+      class Key
+        # A (kind, ID/name) pair used to construct a key path.
+        #
+        # If either name or ID is set, the element is complete.
+        # If neither is set, the element is incomplete.
+        # @!attribute [rw] kind
+        #   @return [String]
+        #     The kind of the entity.
+        #     A kind matching regex +__.*__+ is reserved/read-only.
+        #     A kind must not contain more than 1500 bytes when UTF-8 encoded.
+        #     Cannot be +""+.
+        # @!attribute [rw] id
+        #   @return [Integer]
+        #     The auto-allocated ID of the entity.
+        #     Never equal to zero. Values less than zero are discouraged and may not
+        #     be supported in the future.
+        # @!attribute [rw] name
+        #   @return [String]
+        #     The name of the entity.
+        #     A name matching regex +__.*__+ is reserved/read-only.
+        #     A name must not be more than 1500 bytes when UTF-8 encoded.
+        #     Cannot be +""+.
+        class PathElement; end
+      end
+
+      # An array value.
+      # @!attribute [rw] values
+      #   @return [Array<Google::Datastore::V1::Value>]
+      #     Values in the array.
+      #     The order of this array may not be preserved if it contains a mix of
+      #     indexed and unindexed values.
+      class ArrayValue; end
+
+      # A message that can hold any of the supported value types and associated
+      # metadata.
+      # @!attribute [rw] null_value
+      #   @return [Google::Protobuf::NullValue]
+      #     A null value.
+      # @!attribute [rw] boolean_value
+      #   @return [true, false]
+      #     A boolean value.
+      # @!attribute [rw] integer_value
+      #   @return [Integer]
+      #     An integer value.
+      # @!attribute [rw] double_value
+      #   @return [Float]
+      #     A double value.
+      # @!attribute [rw] timestamp_value
+      #   @return [Google::Protobuf::Timestamp]
+      #     A timestamp value.
+      #     When stored in the Datastore, precise only to microseconds;
+      #     any additional precision is rounded down.
+      # @!attribute [rw] key_value
+      #   @return [Google::Datastore::V1::Key]
+      #     A key value.
+      # @!attribute [rw] string_value
+      #   @return [String]
+      #     A UTF-8 encoded string value.
+      #     When +exclude_from_indexes+ is false (it is indexed) , may have at most 1500 bytes.
+      #     Otherwise, may be set to at least 1,000,000 bytes.
+      # @!attribute [rw] blob_value
+      #   @return [String]
+      #     A blob value.
+      #     May have at most 1,000,000 bytes.
+      #     When +exclude_from_indexes+ is false, may have at most 1500 bytes.
+      #     In JSON requests, must be base64-encoded.
+      # @!attribute [rw] geo_point_value
+      #   @return [Google::Type::LatLng]
+      #     A geo point value representing a point on the surface of Earth.
+      # @!attribute [rw] entity_value
+      #   @return [Google::Datastore::V1::Entity]
+      #     An entity value.
+      #
+      #     - May have no key.
+      #     - May have a key with an incomplete key path.
+      #     - May have a reserved/read-only key.
+      # @!attribute [rw] array_value
+      #   @return [Google::Datastore::V1::ArrayValue]
+      #     An array value.
+      #     Cannot contain another array value.
+      #     A +Value+ instance that sets field +array_value+ must not set fields
+      #     +meaning+ or +exclude_from_indexes+.
+      # @!attribute [rw] meaning
+      #   @return [Integer]
+      #     The +meaning+ field should only be populated for backwards compatibility.
+      # @!attribute [rw] exclude_from_indexes
+      #   @return [true, false]
+      #     If the value should be excluded from all indexes including those defined
+      #     explicitly.
+      class Value; end
+
+      # A Datastore data object.
+      #
+      # An entity is limited to 1 megabyte when stored. That _roughly_
+      # corresponds to a limit of 1 megabyte for the serialized form of this
+      # message.
+      # @!attribute [rw] key
+      #   @return [Google::Datastore::V1::Key]
+      #     The entity's key.
+      #
+      #     An entity must have a key, unless otherwise documented (for example,
+      #     an entity in +Value.entity_value+ may have no key).
+      #     An entity's kind is its key path's last element's kind,
+      #     or null if it has no key.
+      # @!attribute [rw] properties
+      #   @return [Hash{String => Google::Datastore::V1::Value}]
+      #     The entity's properties.
+      #     The map's keys are property names.
+      #     A property name matching regex +__.*__+ is reserved.
+      #     A reserved property name is forbidden in certain documented contexts.
+      #     The name must not contain more than 500 characters.
+      #     The name cannot be +""+.
+      class Entity; end
+    end
+  end
+end

data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/query.rb

@@ -0,0 +1,292 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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.
+
+module Google
+  module Datastore
+    module V1
+      # The result of fetching an entity from Datastore.
+      # @!attribute [rw] entity
+      #   @return [Google::Datastore::V1::Entity]
+      #     The resulting entity.
+      # @!attribute [rw] version
+      #   @return [Integer]
+      #     The version of the entity, a strictly positive number that monotonically
+      #     increases with changes to the entity.
+      #
+      #     This field is set for +FULL+ entity
+      #     results.
+      #
+      #     For Missing entities in +LookupResponse+, this
+      #     is the version of the snapshot that was used to look up the entity, and it
+      #     is always set except for eventually consistent reads.
+      # @!attribute [rw] cursor
+      #   @return [String]
+      #     A cursor that points to the position after the result entity.
+      #     Set only when the +EntityResult+ is part of a +QueryResultBatch+ message.
+      class EntityResult
+        # Specifies what data the 'entity' field contains.
+        # A +ResultType+ is either implied (for example, in +LookupResponse.missing+
+        # from +datastore.proto+, it is always +KEY_ONLY+) or specified by context
+        # (for example, in message +QueryResultBatch+, field +entity_result_type+
+        # specifies a +ResultType+ for all the values in field +entity_results+).
+        module ResultType
+          # Unspecified. This value is never used.
+          RESULT_TYPE_UNSPECIFIED = 0
+
+          # The key and properties.
+          FULL = 1
+
+          # A projected subset of properties. The entity may have no key.
+          PROJECTION = 2
+
+          # Only the key.
+          KEY_ONLY = 3
+        end
+      end
+
+      # A query for entities.
+      # @!attribute [rw] projection
+      #   @return [Array<Google::Datastore::V1::Projection>]
+      #     The projection to return. Defaults to returning all properties.
+      # @!attribute [rw] kind
+      #   @return [Array<Google::Datastore::V1::KindExpression>]
+      #     The kinds to query (if empty, returns entities of all kinds).
+      #     Currently at most 1 kind may be specified.
+      # @!attribute [rw] filter
+      #   @return [Google::Datastore::V1::Filter]
+      #     The filter to apply.
+      # @!attribute [rw] order
+      #   @return [Array<Google::Datastore::V1::PropertyOrder>]
+      #     The order to apply to the query results (if empty, order is unspecified).
+      # @!attribute [rw] distinct_on
+      #   @return [Array<Google::Datastore::V1::PropertyReference>]
+      #     The properties to make distinct. The query results will contain the first
+      #     result for each distinct combination of values for the given properties
+      #     (if empty, all results are returned).
+      # @!attribute [rw] start_cursor
+      #   @return [String]
+      #     A starting point for the query results. Query cursors are
+      #     returned in query result batches and
+      #     {can only be used to continue the same query}[https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets].
+      # @!attribute [rw] end_cursor
+      #   @return [String]
+      #     An ending point for the query results. Query cursors are
+      #     returned in query result batches and
+      #     {can only be used to limit the same query}[https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets].
+      # @!attribute [rw] offset
+      #   @return [Integer]
+      #     The number of results to skip. Applies before limit, but after all other
+      #     constraints. Optional. Must be >= 0 if specified.
+      # @!attribute [rw] limit
+      #   @return [Google::Protobuf::Int32Value]
+      #     The maximum number of results to return. Applies after all other
+      #     constraints. Optional.
+      #     Unspecified is interpreted as no limit.
+      #     Must be >= 0 if specified.
+      class Query; end
+
+      # A representation of a kind.
+      # @!attribute [rw] name
+      #   @return [String]
+      #     The name of the kind.
+      class KindExpression; end
+
+      # A reference to a property relative to the kind expressions.
+      # @!attribute [rw] name
+      #   @return [String]
+      #     The name of the property.
+      #     If name includes "."s, it may be interpreted as a property name path.
+      class PropertyReference; end
+
+      # A representation of a property in a projection.
+      # @!attribute [rw] property
+      #   @return [Google::Datastore::V1::PropertyReference]
+      #     The property to project.
+      class Projection; end
+
+      # The desired order for a specific property.
+      # @!attribute [rw] property
+      #   @return [Google::Datastore::V1::PropertyReference]
+      #     The property to order by.
+      # @!attribute [rw] direction
+      #   @return [Google::Datastore::V1::PropertyOrder::Direction]
+      #     The direction to order by. Defaults to +ASCENDING+.
+      class PropertyOrder
+        # The sort direction.
+        module Direction
+          # Unspecified. This value must not be used.
+          DIRECTION_UNSPECIFIED = 0
+
+          # Ascending.
+          ASCENDING = 1
+
+          # Descending.
+          DESCENDING = 2
+        end
+      end
+
+      # A holder for any type of filter.
+      # @!attribute [rw] composite_filter
+      #   @return [Google::Datastore::V1::CompositeFilter]
+      #     A composite filter.
+      # @!attribute [rw] property_filter
+      #   @return [Google::Datastore::V1::PropertyFilter]
+      #     A filter on a property.
+      class Filter; end
+
+      # A filter that merges multiple other filters using the given operator.
+      # @!attribute [rw] op
+      #   @return [Google::Datastore::V1::CompositeFilter::Operator]
+      #     The operator for combining multiple filters.
+      # @!attribute [rw] filters
+      #   @return [Array<Google::Datastore::V1::Filter>]
+      #     The list of filters to combine.
+      #     Must contain at least one filter.
+      class CompositeFilter
+        # A composite filter operator.
+        module Operator
+          # Unspecified. This value must not be used.
+          OPERATOR_UNSPECIFIED = 0
+
+          # The results are required to satisfy each of the combined filters.
+          AND = 1
+        end
+      end
+
+      # A filter on a specific property.
+      # @!attribute [rw] property
+      #   @return [Google::Datastore::V1::PropertyReference]
+      #     The property to filter by.
+      # @!attribute [rw] op
+      #   @return [Google::Datastore::V1::PropertyFilter::Operator]
+      #     The operator to filter by.
+      # @!attribute [rw] value
+      #   @return [Google::Datastore::V1::Value]
+      #     The value to compare the property to.
+      class PropertyFilter
+        # A property filter operator.
+        module Operator
+          # Unspecified. This value must not be used.
+          OPERATOR_UNSPECIFIED = 0
+
+          # Less than.
+          LESS_THAN = 1
+
+          # Less than or equal.
+          LESS_THAN_OR_EQUAL = 2
+
+          # Greater than.
+          GREATER_THAN = 3
+
+          # Greater than or equal.
+          GREATER_THAN_OR_EQUAL = 4
+
+          # Equal.
+          EQUAL = 5
+
+          # Has ancestor.
+          HAS_ANCESTOR = 11
+        end
+      end
+
+      # A {GQL query}[https://cloud.google.com/datastore/docs/apis/gql/gql_reference].
+      # @!attribute [rw] query_string
+      #   @return [String]
+      #     A string of the format described
+      #     {here}[https://cloud.google.com/datastore/docs/apis/gql/gql_reference].
+      # @!attribute [rw] allow_literals
+      #   @return [true, false]
+      #     When false, the query string must not contain any literals and instead must
+      #     bind all values. For example,
+      #     +SELECT * FROM Kind WHERE a = 'string literal'+ is not allowed, while
+      #     +SELECT * FROM Kind WHERE a = @value+ is.
+      # @!attribute [rw] named_bindings
+      #   @return [Hash{String => Google::Datastore::V1::GqlQueryParameter}]
+      #     For each non-reserved named binding site in the query string, there must be
+      #     a named parameter with that name, but not necessarily the inverse.
+      #
+      #     Key must match regex +[A-Za-z_$][A-Za-z_$0-9]*+, must not match regex
+      #     +__.*__+, and must not be +""+.
+      # @!attribute [rw] positional_bindings
+      #   @return [Array<Google::Datastore::V1::GqlQueryParameter>]
+      #     Numbered binding site @1 references the first numbered parameter,
+      #     effectively using 1-based indexing, rather than the usual 0.
+      #
+      #     For each binding site numbered i in +query_string+, there must be an i-th
+      #     numbered parameter. The inverse must also be true.
+      class GqlQuery; end
+
+      # A binding parameter for a GQL query.
+      # @!attribute [rw] value
+      #   @return [Google::Datastore::V1::Value]
+      #     A value parameter.
+      # @!attribute [rw] cursor
+      #   @return [String]
+      #     A query cursor. Query cursors are returned in query
+      #     result batches.
+      class GqlQueryParameter; end
+
+      # A batch of results produced by a query.
+      # @!attribute [rw] skipped_results
+      #   @return [Integer]
+      #     The number of results skipped, typically because of an offset.
+      # @!attribute [rw] skipped_cursor
+      #   @return [String]
+      #     A cursor that points to the position after the last skipped result.
+      #     Will be set when +skipped_results+ != 0.
+      # @!attribute [rw] entity_result_type
+      #   @return [Google::Datastore::V1::EntityResult::ResultType]
+      #     The result type for every entity in +entity_results+.
+      # @!attribute [rw] entity_results
+      #   @return [Array<Google::Datastore::V1::EntityResult>]
+      #     The results for this batch.
+      # @!attribute [rw] end_cursor
+      #   @return [String]
+      #     A cursor that points to the position after the last result in the batch.
+      # @!attribute [rw] more_results
+      #   @return [Google::Datastore::V1::QueryResultBatch::MoreResultsType]
+      #     The state of the query after the current batch.
+      # @!attribute [rw] snapshot_version
+      #   @return [Integer]
+      #     The version number of the snapshot this batch was returned from.
+      #     This applies to the range of results from the query's +start_cursor+ (or
+      #     the beginning of the query if no cursor was given) to this batch's
+      #     +end_cursor+ (not the query's +end_cursor+).
+      #
+      #     In a single transaction, subsequent query result batches for the same query
+      #     can have a greater snapshot version number. Each batch's snapshot version
+      #     is valid for all preceding batches.
+      class QueryResultBatch
+        # The possible values for the +more_results+ field.
+        module MoreResultsType
+          # Unspecified. This value is never used.
+          MORE_RESULTS_TYPE_UNSPECIFIED = 0
+
+          # There may be additional batches to fetch from this query.
+          NOT_FINISHED = 1
+
+          # The query is finished, but there may be more results after the limit.
+          MORE_RESULTS_AFTER_LIMIT = 2
+
+          # The query is finished, but there may be more results after the end
+          # cursor.
+          MORE_RESULTS_AFTER_CURSOR = 4
+
+          # The query has been exhausted.
+          NO_MORE_RESULTS = 3
+        end
+      end
+    end
+  end
+end