google-cloud-firestore 0.24.2 → 0.25.0

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

@@ -0,0 +1,219 @@
+# Copyright 2019 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
+#
+#     https://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 Firestore
+    module V1
+      # A Firestore query.
+      # @!attribute [rw] select
+      #   @return [Google::Firestore::V1::StructuredQuery::Projection]
+      #     The projection to return.
+      # @!attribute [rw] from
+      #   @return [Array<Google::Firestore::V1::StructuredQuery::CollectionSelector>]
+      #     The collections to query.
+      # @!attribute [rw] where
+      #   @return [Google::Firestore::V1::StructuredQuery::Filter]
+      #     The filter to apply.
+      # @!attribute [rw] order_by
+      #   @return [Array<Google::Firestore::V1::StructuredQuery::Order>]
+      #     The order to apply to the query results.
+      #
+      #     Firestore guarantees a stable ordering through the following rules:
+      #
+      #     * Any field required to appear in `order_by`, that is not already
+      #       specified in `order_by`, is appended to the order in field name order
+      #       by default.
+      #     * If an order on `__name__` is not specified, it is appended by default.
+      #
+      #     Fields are appended with the same sort direction as the last order
+      #     specified, or 'ASCENDING' if no order was specified. For example:
+      #
+      #     * `SELECT * FROM Foo ORDER BY A` becomes
+      #       `SELECT * FROM Foo ORDER BY A, __name__`
+      #     * `SELECT * FROM Foo ORDER BY A DESC` becomes
+      #       `SELECT * FROM Foo ORDER BY A DESC, __name__ DESC`
+      #     * `SELECT * FROM Foo WHERE A > 1` becomes
+      #       `SELECT * FROM Foo WHERE A > 1 ORDER BY A, __name__`
+      # @!attribute [rw] start_at
+      #   @return [Google::Firestore::V1::Cursor]
+      #     A starting point for the query results.
+      # @!attribute [rw] end_at
+      #   @return [Google::Firestore::V1::Cursor]
+      #     A end point for the query results.
+      # @!attribute [rw] offset
+      #   @return [Integer]
+      #     The number of results to skip.
+      #
+      #     Applies before limit, but after all other constraints. Must be >= 0 if
+      #     specified.
+      # @!attribute [rw] limit
+      #   @return [Google::Protobuf::Int32Value]
+      #     The maximum number of results to return.
+      #
+      #     Applies after all other constraints.
+      #     Must be >= 0 if specified.
+      class StructuredQuery
+        # A selection of a collection, such as `messages as m1`.
+        # @!attribute [rw] collection_id
+        #   @return [String]
+        #     The collection ID.
+        #     When set, selects only collections with this ID.
+        # @!attribute [rw] all_descendants
+        #   @return [true, false]
+        #     When false, selects only collections that are immediate children of
+        #     the `parent` specified in the containing `RunQueryRequest`.
+        #     When true, selects all descendant collections.
+        class CollectionSelector; end
+
+        # A filter.
+        # @!attribute [rw] composite_filter
+        #   @return [Google::Firestore::V1::StructuredQuery::CompositeFilter]
+        #     A composite filter.
+        # @!attribute [rw] field_filter
+        #   @return [Google::Firestore::V1::StructuredQuery::FieldFilter]
+        #     A filter on a document field.
+        # @!attribute [rw] unary_filter
+        #   @return [Google::Firestore::V1::StructuredQuery::UnaryFilter]
+        #     A filter that takes exactly one argument.
+        class Filter; end
+
+        # A filter that merges multiple other filters using the given operator.
+        # @!attribute [rw] op
+        #   @return [Google::Firestore::V1::StructuredQuery::CompositeFilter::Operator]
+        #     The operator for combining multiple filters.
+        # @!attribute [rw] filters
+        #   @return [Array<Google::Firestore::V1::StructuredQuery::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 field.
+        # @!attribute [rw] field
+        #   @return [Google::Firestore::V1::StructuredQuery::FieldReference]
+        #     The field to filter by.
+        # @!attribute [rw] op
+        #   @return [Google::Firestore::V1::StructuredQuery::FieldFilter::Operator]
+        #     The operator to filter by.
+        # @!attribute [rw] value
+        #   @return [Google::Firestore::V1::Value]
+        #     The value to compare to.
+        class FieldFilter
+          # A field filter operator.
+          module Operator
+            # Unspecified. This value must not be used.
+            OPERATOR_UNSPECIFIED = 0
+
+            # Less than. Requires that the field come first in `order_by`.
+            LESS_THAN = 1
+
+            # Less than or equal. Requires that the field come first in `order_by`.
+            LESS_THAN_OR_EQUAL = 2
+
+            # Greater than. Requires that the field come first in `order_by`.
+            GREATER_THAN = 3
+
+            # Greater than or equal. Requires that the field come first in
+            # `order_by`.
+            GREATER_THAN_OR_EQUAL = 4
+
+            # Equal.
+            EQUAL = 5
+
+            # Contains. Requires that the field is an array.
+            ARRAY_CONTAINS = 7
+          end
+        end
+
+        # A filter with a single operand.
+        # @!attribute [rw] op
+        #   @return [Google::Firestore::V1::StructuredQuery::UnaryFilter::Operator]
+        #     The unary operator to apply.
+        # @!attribute [rw] field
+        #   @return [Google::Firestore::V1::StructuredQuery::FieldReference]
+        #     The field to which to apply the operator.
+        class UnaryFilter
+          # A unary operator.
+          module Operator
+            # Unspecified. This value must not be used.
+            OPERATOR_UNSPECIFIED = 0
+
+            # Test if a field is equal to NaN.
+            IS_NAN = 2
+
+            # Test if an exprestion evaluates to Null.
+            IS_NULL = 3
+          end
+        end
+
+        # An order on a field.
+        # @!attribute [rw] field
+        #   @return [Google::Firestore::V1::StructuredQuery::FieldReference]
+        #     The field to order by.
+        # @!attribute [rw] direction
+        #   @return [Google::Firestore::V1::StructuredQuery::Direction]
+        #     The direction to order by. Defaults to `ASCENDING`.
+        class Order; end
+
+        # A reference to a field, such as `max(messages.time) as max_time`.
+        # @!attribute [rw] field_path
+        #   @return [String]
+        class FieldReference; end
+
+        # The projection of document's fields to return.
+        # @!attribute [rw] fields
+        #   @return [Array<Google::Firestore::V1::StructuredQuery::FieldReference>]
+        #     The fields to return.
+        #
+        #     If empty, all fields are returned. To only return the name
+        #     of the document, use `['__name__']`.
+        class Projection; end
+
+        # A sort direction.
+        module Direction
+          # Unspecified.
+          DIRECTION_UNSPECIFIED = 0
+
+          # Ascending.
+          ASCENDING = 1
+
+          # Descending.
+          DESCENDING = 2
+        end
+      end
+
+      # A position in a query result set.
+      # @!attribute [rw] values
+      #   @return [Array<Google::Firestore::V1::Value>]
+      #     The values that represent a position, in the order they appear in
+      #     the order by clause of a query.
+      #
+      #     Can contain fewer values than specified in the order by clause.
+      # @!attribute [rw] before
+      #   @return [true, false]
+      #     If the position is just before or just after the given values, relative
+      #     to the sort order defined by the query.
+      class Cursor; end
+    end
+  end
+end

data/lib/google/cloud/firestore/v1/doc/google/firestore/v1/write.rb

@@ -0,0 +1,237 @@
+# Copyright 2019 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
+#
+#     https://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 Firestore
+    module V1
+      # A write on a document.
+      # @!attribute [rw] update
+      #   @return [Google::Firestore::V1::Document]
+      #     A document to write.
+      # @!attribute [rw] delete
+      #   @return [String]
+      #     A document name to delete. In the format:
+      #     `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
+      # @!attribute [rw] transform
+      #   @return [Google::Firestore::V1::DocumentTransform]
+      #     Applies a tranformation to a document.
+      #     At most one `transform` per document is allowed in a given request.
+      #     An `update` cannot follow a `transform` on the same document in a given
+      #     request.
+      # @!attribute [rw] update_mask
+      #   @return [Google::Firestore::V1::DocumentMask]
+      #     The fields to update in this write.
+      #
+      #     This field can be set only when the operation is `update`.
+      #     If the mask is not set for an `update` and the document exists, any
+      #     existing data will be overwritten.
+      #     If the mask is set and the document on the server has fields not covered by
+      #     the mask, they are left unchanged.
+      #     Fields referenced in the mask, but not present in the input document, are
+      #     deleted from the document on the server.
+      #     The field paths in this mask must not contain a reserved field name.
+      # @!attribute [rw] current_document
+      #   @return [Google::Firestore::V1::Precondition]
+      #     An optional precondition on the document.
+      #
+      #     The write will fail if this is set and not met by the target document.
+      class Write; end
+
+      # A transformation of a document.
+      # @!attribute [rw] document
+      #   @return [String]
+      #     The name of the document to transform.
+      # @!attribute [rw] field_transforms
+      #   @return [Array<Google::Firestore::V1::DocumentTransform::FieldTransform>]
+      #     The list of transformations to apply to the fields of the document, in
+      #     order.
+      #     This must not be empty.
+      class DocumentTransform
+        # A transformation of a field of the document.
+        # @!attribute [rw] field_path
+        #   @return [String]
+        #     The path of the field. See {Google::Firestore::V1::Document#fields Document#fields} for the field path syntax
+        #     reference.
+        # @!attribute [rw] set_to_server_value
+        #   @return [Google::Firestore::V1::DocumentTransform::FieldTransform::ServerValue]
+        #     Sets the field to the given server value.
+        # @!attribute [rw] increment
+        #   @return [Google::Firestore::V1::Value]
+        #     Adds the given value to the field's current value.
+        #
+        #     This must be an integer or a double value.
+        #     If the field is not an integer or double, or if the field does not yet
+        #     exist, the transformation will set the field to the given value.
+        #     If either of the given value or the current field value are doubles,
+        #     both values will be interpreted as doubles. Double arithmetic and
+        #     representation of double values follow IEEE 754 semantics.
+        #     If there is positive/negative integer overflow, the field is resolved
+        #     to the largest magnitude positive/negative integer.
+        # @!attribute [rw] maximum
+        #   @return [Google::Firestore::V1::Value]
+        #     Sets the field to the maximum of its current value and the given value.
+        #
+        #     This must be an integer or a double value.
+        #     If the field is not an integer or double, or if the field does not yet
+        #     exist, the transformation will set the field to the given value.
+        #     If a maximum operation is applied where the field and the input value
+        #     are of mixed types (that is - one is an integer and one is a double)
+        #     the field takes on the type of the larger operand. If the operands are
+        #     equivalent (e.g. 3 and 3.0), the field does not change.
+        #     0, 0.0, and -0.0 are all zero. The maximum of a zero stored value and
+        #     zero input value is always the stored value.
+        #     The maximum of any numeric value x and NaN is NaN.
+        # @!attribute [rw] minimum
+        #   @return [Google::Firestore::V1::Value]
+        #     Sets the field to the minimum of its current value and the given value.
+        #
+        #     This must be an integer or a double value.
+        #     If the field is not an integer or double, or if the field does not yet
+        #     exist, the transformation will set the field to the input value.
+        #     If a minimum operation is applied where the field and the input value
+        #     are of mixed types (that is - one is an integer and one is a double)
+        #     the field takes on the type of the smaller operand. If the operands are
+        #     equivalent (e.g. 3 and 3.0), the field does not change.
+        #     0, 0.0, and -0.0 are all zero. The minimum of a zero stored value and
+        #     zero input value is always the stored value.
+        #     The minimum of any numeric value x and NaN is NaN.
+        # @!attribute [rw] append_missing_elements
+        #   @return [Google::Firestore::V1::ArrayValue]
+        #     Append the given elements in order if they are not already present in
+        #     the current field value.
+        #     If the field is not an array, or if the field does not yet exist, it is
+        #     first set to the empty array.
+        #
+        #     Equivalent numbers of different types (e.g. 3L and 3.0) are
+        #     considered equal when checking if a value is missing.
+        #     NaN is equal to NaN, and Null is equal to Null.
+        #     If the input contains multiple equivalent values, only the first will
+        #     be considered.
+        #
+        #     The corresponding transform_result will be the null value.
+        # @!attribute [rw] remove_all_from_array
+        #   @return [Google::Firestore::V1::ArrayValue]
+        #     Remove all of the given elements from the array in the field.
+        #     If the field is not an array, or if the field does not yet exist, it is
+        #     set to the empty array.
+        #
+        #     Equivalent numbers of the different types (e.g. 3L and 3.0) are
+        #     considered equal when deciding whether an element should be removed.
+        #     NaN is equal to NaN, and Null is equal to Null.
+        #     This will remove all equivalent values if there are duplicates.
+        #
+        #     The corresponding transform_result will be the null value.
+        class FieldTransform
+          # A value that is calculated by the server.
+          module ServerValue
+            # Unspecified. This value must not be used.
+            SERVER_VALUE_UNSPECIFIED = 0
+
+            # The time at which the server processed the request, with millisecond
+            # precision.
+            REQUEST_TIME = 1
+          end
+        end
+      end
+
+      # The result of applying a write.
+      # @!attribute [rw] update_time
+      #   @return [Google::Protobuf::Timestamp]
+      #     The last update time of the document after applying the write. Not set
+      #     after a `delete`.
+      #
+      #     If the write did not actually change the document, this will be the
+      #     previous update_time.
+      # @!attribute [rw] transform_results
+      #   @return [Array<Google::Firestore::V1::Value>]
+      #     The results of applying each {Google::Firestore::V1::DocumentTransform::FieldTransform DocumentTransform::FieldTransform}, in the
+      #     same order.
+      class WriteResult; end
+
+      # A {Google::Firestore::V1::Document Document} has changed.
+      #
+      # May be the result of multiple {Google::Firestore::V1::Write writes}, including deletes, that
+      # ultimately resulted in a new value for the {Google::Firestore::V1::Document Document}.
+      #
+      # Multiple {Google::Firestore::V1::DocumentChange DocumentChange} messages may be returned for the same logical
+      # change, if multiple targets are affected.
+      # @!attribute [rw] document
+      #   @return [Google::Firestore::V1::Document]
+      #     The new state of the {Google::Firestore::V1::Document Document}.
+      #
+      #     If `mask` is set, contains only fields that were updated or added.
+      # @!attribute [rw] target_ids
+      #   @return [Array<Integer>]
+      #     A set of target IDs of targets that match this document.
+      # @!attribute [rw] removed_target_ids
+      #   @return [Array<Integer>]
+      #     A set of target IDs for targets that no longer match this document.
+      class DocumentChange; end
+
+      # A {Google::Firestore::V1::Document Document} has been deleted.
+      #
+      # May be the result of multiple {Google::Firestore::V1::Write writes}, including updates, the
+      # last of which deleted the {Google::Firestore::V1::Document Document}.
+      #
+      # Multiple {Google::Firestore::V1::DocumentDelete DocumentDelete} messages may be returned for the same logical
+      # delete, if multiple targets are affected.
+      # @!attribute [rw] document
+      #   @return [String]
+      #     The resource name of the {Google::Firestore::V1::Document Document} that was deleted.
+      # @!attribute [rw] removed_target_ids
+      #   @return [Array<Integer>]
+      #     A set of target IDs for targets that previously matched this entity.
+      # @!attribute [rw] read_time
+      #   @return [Google::Protobuf::Timestamp]
+      #     The read timestamp at which the delete was observed.
+      #
+      #     Greater or equal to the `commit_time` of the delete.
+      class DocumentDelete; end
+
+      # A {Google::Firestore::V1::Document Document} has been removed from the view of the targets.
+      #
+      # Sent if the document is no longer relevant to a target and is out of view.
+      # Can be sent instead of a DocumentDelete or a DocumentChange if the server
+      # can not send the new value of the document.
+      #
+      # Multiple {Google::Firestore::V1::DocumentRemove DocumentRemove} messages may be returned for the same logical
+      # write or delete, if multiple targets are affected.
+      # @!attribute [rw] document
+      #   @return [String]
+      #     The resource name of the {Google::Firestore::V1::Document Document} that has gone out of view.
+      # @!attribute [rw] removed_target_ids
+      #   @return [Array<Integer>]
+      #     A set of target IDs for targets that previously matched this document.
+      # @!attribute [rw] read_time
+      #   @return [Google::Protobuf::Timestamp]
+      #     The read timestamp at which the remove was observed.
+      #
+      #     Greater or equal to the `commit_time` of the change/delete/remove.
+      class DocumentRemove; end
+
+      # A digest of all the documents that match a given target.
+      # @!attribute [rw] target_id
+      #   @return [Integer]
+      #     The target ID to which this filter applies.
+      # @!attribute [rw] count
+      #   @return [Integer]
+      #     The total count of documents that match {Google::Firestore::V1::ExistenceFilter#target_id target_id}.
+      #
+      #     If different from the count of documents in the client that match, the
+      #     client must manually determine which documents no longer match the target.
+      class ExistenceFilter; end
+    end
+  end
+end