tarantool / tarantool/doc

Introduce logical combinators for filters (C API)

Open
#5,327 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

3.5 c api
Dominant language
CSS
Stars
15
Forks
49
Avg merge
1d 13h
Merged PRs (30d)
3

Description

Product: Tarantool EE
Since: 3.5

Now one can combine several ArrowStream filters with logical AND and OR
combinators:

/* Create arrow stream options. */
box_arrow_options_t *options = box_arrow_options_new();

/* [2] >= 42 */
box_filter_t filter1;
filter1->type = FILTER_TYPE_GE;
filter1->field_no = 1; /* 0-indexation. */
char buf1[16];
mp_encode_uint(buf1, 42);
filter1->value = buf1;

/* [3] == 1 */
box_filter_t filter2;
filter2->type = FILTER_TYPE_EQ;
filter2->field_no = 2; /* 0-indexation. */
char buf2[16];
mp_encode_uint(buf2, 1);
filter2->value = buf2;

/* [1] < 20 */
box_filter_t filter3;
filter3->type = FILTER_TYPE_LT;
filter3->field_no = 1; /* 0-indexation. */
char buf3[16];
mp_encode_uint(buf3, 20);
filter3->value = buf3;

/* [2] >= 42 AND [3] == 1 */
box_filter_t filter_and;
filter_and->type = FILTER_TYPE_AND;
box_filter_t *chidlren_and[] = {&filter1, &filter2};
filter_and->children = children_and;
filter_and->chidlren_count = 2;

/* ([2] >= 42 AND [3] == 1) OR [1] < 20 */
box_filter_t filter_or;
filter_or->type = FILTER_TYPE_OR;
box_filter_t *chidlren_or[] = {&filter_and, &filter3};
filter_and->children = children_or;
filter_and->chidlren_count = 2;

box_arrow_options_set_filter(options, &filter_or);

/* Create stream. */
struct ArrowArrayStream stream;
int rc = box_index_arrow_stream(space_id, index_id, field_count, fields,
				key, key + key_size, options, &stream);

Note that the expressions are not optimized at all - each expression is
checked from the first to the last child until we understand that the
filter is satisfied, so it makes sense to place the most rare conditions
first for AND combinators and to place them last for OR combinators.
Requested by @drewdzzz in https://github.com/tarantool/tarantool-ee/commit/297f88dfb4a257ee50d9e8ba1b5ec7629a662264.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the C API documentation for box_arrow_options_set_filter and box_index_arrow_stream, then review the existing ArrowStream filter reference. Document FILTER_TYPE_AND and FILTER_TYPE_OR with the provided nested example and evaluation-order note; done means the combinators and their behavior are covered in the relevant API documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.