@callback batch_get(batch_gets()) :: {:ok, Keyword.t()} | {:error, term()}

Batch get several rows of data from one or more tables, this batch request put multiple get_row in one request from client's perspective.

After execute each operation in servers, return results independently and independently consumes capacity units.

When input schema_entity, only theirs primary keys are used in query, if need to use theirs attribute columns into condition of query, please use entity_full_match: true option to do that.

Example

When the schema has only 1 primary key, and you use default options:

# get_row style
batch_get([
  {Schema1, [[{"id", 1}], [{"id", 2}]]},
  {Schema2, [[{"id", 3}], [{"id", 4}]]}
])

# get_row style
# if only get one row from one schema could also be:
batch_get([
  {Schema1, [{"id", 1}]},
  {Schema2, [{"id", 3}]}
])

# schema_entity style
batch_get([
  [%Schema1{id: 1}, %Schema1{id: 2}],
  [%Schema2{id: 3}, %Schema2{id: 4}]
])

When the schema has only 1 primary key, and you use custom options:

# get_row style
batch_get([
  {Schema1, [{"id", 1}], [{"id", 2}], columns_to_get: ["field1"]},
  {Schema2, [{"id", 3}], [{"id", 4}], columns_to_get: ["field2"]}
])

# schema_entity style
batch_get([
  {
    [%Schema1{id: 1}, %Schema1{id: 2}],
    columns_to_get: ["field1"]
  },
  {
    [%Schema2{id: 3}, %Schema2{id: 4}],
    columns_to_get: ["field2"]
  }
])

Entity full match:

# only schema_entity style
batch_get([
  {
    [%Schema1{id: 1, field1: 10}, %Schema1{id: 2, field1: 20}],
    entity_full_match: true
  },
  {
    [%Schema2{id: 3, field2: 30}, %Schema2{id: 4, field2: 40}],
    entity_full_match: true
  }
])

When the schema has multiple primary keys:

# get_row style
batch_get([
  {Schema3, [
    [{"id", 1}, {"another_pk", "example1"}],
    [{"id", 2}, {"another_pk", "example2"}]
  ]},
  {Schema4, [
    [{"id", 3}, {"another_pk", "example3"}],
    [{"id", 4}, {"another_pk", "example4"}]
  ]}
])

# schema_entity style
batch_get([
  [
    %Schema3{id: 1, another_pk: "example1"},
    %Schema3{id: 2, another_pk: "example2"}
  ],
  [
    %Schema4{id: 3, another_pk: "example3"},
    %Schema4{id: 4, another_pk: "example4"}
  ]
])

@callback get(schema(), ids :: list(), options()) :: schema() | {:error, term()} | nil

Fetch a single struct from tablestore where the whole primary key(s) match the given ids.

Options

• :columns_to_get, string list, return the specified attribute columns, if not specify this option field, will try to return all attribute columns together.

• :start_column, string, used as a starting column for Wide Column read, the return result contains this as starter.

• :end_column, string, used as a ending column for Wide Column read, the return result DON NOT contain this column.

• :filter, used as a filter by condition, support ">", "<", ">=", "<=", "==", "and", "or" and "()" expressions.

  The ignore_if_missing option can be used for the non-existed attribute column, for example:

  An attribute column does not exist meanwhile set it as true, will ignore this match condition in the return result;

  An existed attribute column DOES NOT suit for this use case, the match condition will always affect the return result, if match condition does not satisfy, they won't be return in result.

    filter: filter(({"name", ignore_if_missing: true} == var_name and "age" > 1) or ("class" == "1"))

• :transaction_id, read under local transaction in a partition key.

@callback get_range(schema(), options()) ::
  {list() | nil, next_token()} | {:error, term()}

Get multiple structs by range to the schema, result in :forward direction by default.

Example

Simply get result in a range request:

Repo.get_range(Order)
Repo.get_range(Order, direction: :backward)

If the Order schema has multiple primary keys, and the :id field is the partition key, we can get records in range under the partition key "1" in this way:

Repo.get_range(%Order{id: "1"})

Options

See get_range/4.

@callback get_range(schema(), start_primary_keys(), end_primary_keys(), options()) ::
  {list() | nil, next_token()} | {:error, term()}

Get multiple structs by range from one table, rely on the conjunction of the partition key and other primary key(s).

Options

• :direction, by default it is :forward, set it as :forward to make the order of the query result in ascending by primary key(s), set it as :backward to make the order of the query result in descending by primary key(s).

• :columns_to_get, string list, return the specified attribute columns, if not specify this field all attribute columns will be return.

• :start_column, string, used as a starting column for Wide Column read, the return result contains this as starter.

• :end_column, string, used as a ending column for Wide Column read, the return result DON NOT contain this column.

• :limit, optional, the maximum number of rows of data to be returned, this value must be greater than 0, whether this option is set or not, there returns a maximum of 5,000 data rows and the total data size never exceeds 4 MB.

• :transaction_id, read under local transaction in a partition key.

• :filter, used as a filter by condition, support ">", "<", ">=", "<=", "==", "and", "or" and "()" expressions.

  The ignore_if_missing option can be used for the non-existed attribute column, for example:

  An attribute column does not exist meanwhile set it as true, will ignore this match condition in the return result;

  An existed attribute column DOES NOT suit for this use case, the match condition will always affect the return result, if match condition does not satisfy, they won't be return in result.

    filter: filter(({"name", ignore_if_missing: true} == var_name and "age" > 1) or ("class" == "1"))

@callback one(schema(), options()) :: schema() | {:error, term()} | nil

Similar to get/3, please ensure schema entity has been filled with the whole primary key(s).

Options

• :entity_full_match, whether to transfer the input attribute column(s) into the :== filtering expressions, by default it is false, when set entity_full_match: true, please notice the following rules:

  • If there exists attribute column(s) provided in entity, these fields will be combined within multiple :== filtering expressions;

  • If there exists attribute column(s) provided and meanwhile set filter option, they will be merged into a composite filter.

Other options please refer get/3.

@callback one!(schema(), options()) :: schema() | {:error, term()} | nil

See one/2 for more details.

@callback search(schema(), index_name(), options()) ::
  {:ok, search_result()} | {:error, term()}

Provide search index features for the following scenarios:

• MatchAllQuery
• MatchQuery
• MatchPhraseQuery
• TermQuery
• TermsQuery
• PrefixQuery
• RangeQuery
• WildcardQuery
• BoolQuery
• NestedQuery
• ExistsQuery
• GeoBoundingBoxQuery
• GeoDistanceQuery
• GeoPolygonQuery

Please refer ExAliyunOts.Search query section for details, they are similar options for use, for example:

MyRepo.search(MySchema, "index_name",
  search_query: [
    query: exists_query("comment")
  ]
)

@callback sql_query(schema(), sql_query()) :: {:ok, [schema()]} | {:error, term()}

Use SQL query data, only support select query.

Example

sql_query(Schema1, "SELECT * FROM table LIMIT 20")

@callback stream(schema(), options()) :: Enumerable.t()

As a wrapper built on stream_range/4 to create composable and lazy enumerables stream for iteration.

Options

Please see options of get_range/4 for details.

@callback stream_range(schema(), start_primary_keys(), end_primary_keys(), options()) ::
  Enumerable.t()

As a wrapper built on ExAliyunOts.stream_range/5 to create composable and lazy enumerables stream for iteration.

Options

Please see options of get_range/4 for details.

@callback stream_search(schema(), index_name(), options()) :: Enumerable.t()

As a wrapper built on ExAliyunOts.stream_search/4 to create composable and lazy enumerables stream for iteration.

Options

Please see options of search/3 for details.