# Copyright 2018 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 Spanner
    module V1
      # KeyRange represents a range of rows in a table or index.
      #
      # A range has a start key and an end key. These keys can be open or
      # closed, indicating if the range includes rows with that key.
      #
      # Keys are represented by lists, where the ith value in the list
      # corresponds to the ith component of the table or index primary key.
      # Individual values are encoded as described {Google::Spanner::V1::TypeCode here}.
      #
      # For example, consider the following table definition:
      #
      #     CREATE TABLE UserEvents (
      #       UserName STRING(MAX),
      #       EventDate STRING(10)
      #     ) PRIMARY KEY(UserName, EventDate);
      #
      # The following keys name rows in this table:
      #
      #     ["Bob", "2014-09-23"]
      #     ["Alfred", "2015-06-12"]
      #
      # Since the +UserEvents+ table's +PRIMARY KEY+ clause names two
      # columns, each +UserEvents+ key has two elements; the first is the
      # +UserName+, and the second is the +EventDate+.
      #
      # Key ranges with multiple components are interpreted
      # lexicographically by component using the table or index key's declared
      # sort order. For example, the following range returns all events for
      # user +"Bob"+ that occurred in the year 2015:
      #
      #     "start_closed": ["Bob", "2015-01-01"]
      #     "end_closed": ["Bob", "2015-12-31"]
      #
      # Start and end keys can omit trailing key components. This affects the
      # inclusion and exclusion of rows that exactly match the provided key
      # components: if the key is closed, then rows that exactly match the
      # provided components are included; if the key is open, then rows
      # that exactly match are not included.
      #
      # For example, the following range includes all events for +"Bob"+ that
      # occurred during and after the year 2000:
      #
      #     "start_closed": ["Bob", "2000-01-01"]
      #     "end_closed": ["Bob"]
      #
      # The next example retrieves all events for +"Bob"+:
      #
      #     "start_closed": ["Bob"]
      #     "end_closed": ["Bob"]
      #
      # To retrieve events before the year 2000:
      #
      #     "start_closed": ["Bob"]
      #     "end_open": ["Bob", "2000-01-01"]
      #
      # The following range includes all rows in the table:
      #
      #     "start_closed": []
      #     "end_closed": []
      #
      # This range returns all users whose +UserName+ begins with any
      # character from A to C:
      #
      #     "start_closed": ["A"]
      #     "end_open": ["D"]
      #
      # This range returns all users whose +UserName+ begins with B:
      #
      #     "start_closed": ["B"]
      #     "end_open": ["C"]
      #
      # Key ranges honor column sort order. For example, suppose a table is
      # defined as follows:
      #
      #     CREATE TABLE DescendingSortedTable {
      #       Key INT64,
      #       ...
      #     ) PRIMARY KEY(Key DESC);
      #
      # The following range retrieves all rows with key values between 1
      # and 100 inclusive:
      #
      #     "start_closed": ["100"]
      #     "end_closed": ["1"]
      #
      # Note that 100 is passed as the start, and 1 is passed as the end,
      # because +Key+ is a descending column in the schema.
      # @!attribute [rw] start_closed
      #   @return [Google::Protobuf::ListValue]
      #     If the start is closed, then the range includes all rows whose
      #     first +len(start_closed)+ key columns exactly match +start_closed+.
      # @!attribute [rw] start_open
      #   @return [Google::Protobuf::ListValue]
      #     If the start is open, then the range excludes rows whose first
      #     +len(start_open)+ key columns exactly match +start_open+.
      # @!attribute [rw] end_closed
      #   @return [Google::Protobuf::ListValue]
      #     If the end is closed, then the range includes all rows whose
      #     first +len(end_closed)+ key columns exactly match +end_closed+.
      # @!attribute [rw] end_open
      #   @return [Google::Protobuf::ListValue]
      #     If the end is open, then the range excludes rows whose first
      #     +len(end_open)+ key columns exactly match +end_open+.
      class KeyRange; end

      # +KeySet+ defines a collection of Cloud Spanner keys and/or key ranges. All
      # the keys are expected to be in the same table or index. The keys need
      # not be sorted in any particular way.
      #
      # If the same key is specified multiple times in the set (for example
      # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
      # behaves as if the key were only specified once.
      # @!attribute [rw] keys
      #   @return [Array<Google::Protobuf::ListValue>]
      #     A list of specific keys. Entries in +keys+ should have exactly as
      #     many elements as there are columns in the primary or index key
      #     with which this +KeySet+ is used.  Individual key values are
      #     encoded as described {Google::Spanner::V1::TypeCode here}.
      # @!attribute [rw] ranges
      #   @return [Array<Google::Spanner::V1::KeyRange>]
      #     A list of key ranges. See {Google::Spanner::V1::KeyRange KeyRange} for more information about
      #     key range specifications.
      # @!attribute [rw] all
      #   @return [true, false]
      #     For convenience +all+ can be set to +true+ to indicate that this
      #     +KeySet+ matches all keys in the table or index. Note that any keys
      #     specified in +keys+ or +ranges+ are only yielded once.
      class KeySet; end
    end
  end
end