Struct google_cloud_spanner::key::KeyRange

pub struct KeyRange {
    pub kind: RangeKind,
    /* private fields */
}

A KeyRange represents a range of rows in a table or index.

A range has a Start key and an End key. IncludeStart and IncludeEnd indicate whether the Start and End keys are included in the range.

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:

  use google_cloud_spanner::key::Key;
  use google_cloud_spanner::statement::ToKind;
  let key1 = Key::composite(&[&"Bob", &"2014-09-23"]);
  let key2 = Key::composite(&[&"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:

  use google_cloud_spanner::key::{Key, KeyRange, RangeKind};
  use google_cloud_spanner::statement::ToKind;
  let range = KeyRange::new(
      Key::composite(&[&"Bob", &"2015-01-01"]),
      Key::composite(&[&"Bob", &"2015-12-31"]),
      RangeKind::ClosedClosed
  );

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 IncludeStart is true, then rows that exactly match the provided components of the Start key are included; if IncludeStart is false then rows that exactly match are not included. IncludeEnd and End key behave in the same fashion.

For example, the following range includes all events for “Bob” that occurred during and after the year 2000:

  use google_cloud_spanner::key::{Key, KeyRange, RangeKind};
  use google_cloud_spanner::statement::ToKind;
  KeyRange::new(
   Key::composite(&[&"Bob", &"2000-01-01"]),
   Key::key(&"Bob"),
   RangeKind::ClosedClosed
  );

The next example retrieves all events for “Bob”:

Key::key(“Bob”).to_prefix()

To retrieve events before the year 2000:

  use google_cloud_spanner::key::{Key, KeyRange, RangeKind};
  use google_cloud_spanner::statement::ToKind;
  let range = KeyRange::new(
   Key::key(&"Bob"),
   Key::composite(&[&"Bob", &"2000-01-01"]),
   RangeKind::ClosedOpen
  );

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:

  use google_cloud_spanner::key::{Key, KeyRange, RangeKind};
  let range = KeyRange::new(
       Key::key(&100),
       Key::key(&1),
  RangeKind::ClosedClosed,
  );

Note that 100 is passed as the start, and 1 is passed as the end, because Key is a descending column in the schema.

Fields

kind: RangeKind

kind describes whether the boundaries of the key range include their keys.

Implementations

impl KeyRange

pub fn new(start: Key, end: Key, kind: RangeKind) -> KeyRange

Trait Implementations

impl Clone for KeyRange

fn clone(&self) -> KeyRange

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl From<KeyRange> for InternalKeyRange

fn from(key_range: KeyRange) -> Self

Converts to this type from the input type.

impl From<KeyRange> for KeySet

fn from(key_range: KeyRange) -> Self

Converts to this type from the input type.