Идентификация и обработка ограничений IN в xBestIndex

int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);

Данный интерфейс может быть использован только внутри метода xBestIndex() реализации виртуальной таблицы. Результат вызова этого интерфейса из любого другого контекста не определён и, вероятно, вреден.

Ограничение на виртуальной таблице вида "колонка IN (...)" передаётся методу xBestIndex как ограничение SQLITE_INDEX_CONSTRAINT_EQ. Если xBestIndex хочет использовать это ограничение, он должен установить соответствующее aConstraintUsage[].argvIndex на положительное целое число. Затем, в обычном режиме обработки операторов IN, SQLite генерирует байткод, вызывающий метод xFilter() один раз для каждого значения в правой части оператора IN. Таким образом, виртуальная таблица видит только одно значение из правой части оператора IN за раз.

Однако в некоторых случаях для виртуальной таблицы было бы выгодно увидеть все значения в правой части оператора IN сразу. Интерфейсы sqlite3_vtab_in() облегчают это двумя способами:

1. Вызов sqlite3_vtab_in(P,N,-1) вернёт true (ненулевое значение) тогда и только тогда, когда ограничение P->aConstraint[N] является оператором IN, который может быть обработан сразу. Другими словами, sqlite3_vtab_in() с -1 в третьем аргументе — это механизм, с помощью которого виртуальная таблица может спросить SQLite, возможно ли одновременная обработка оператора IN.

2. Вызов sqlite3_vtab_in(P,N,F) с F==1 или F==0 указывает SQLite, что виртуальная таблица хочет или не хочет обрабатывать оператор IN сразу соответственно. Таким образом, когда третий параметр (F) неотрицателен, этот интерфейс является механизмом, с помощью которого виртуальная таблица сообщает SQLite, как она хочет обрабатывать оператор IN.

Интерфейс sqlite3_vtab_in(P,N,F) может быть вызван несколько раз в рамках одного вызова метода xBestIndex. Для любой пары P,N возвращаемое значение sqlite3_vtab_in(P,N,F) всегда будет одинаковым в рамках одного вызова xBestIndex. Если интерфейс возвращает true (ненулевое значение), это означает, что ограничение является оператором IN, который может быть обработан сразу. Если ограничение не является оператором IN или не может быть обработано сразу, интерфейс возвращает false.

Обработка оператора IN сразу выбирается, если выполняются оба следующих условия:

1. Значение P->aConstraintUsage[N].argvIndex установлено на положительное целое число. Таким образом, виртуальная таблица сообщает SQLite, что она хочет использовать N-ое ограничение.

2. Последний вызов sqlite3_vtab_in(P,N,F), для которого F было неотрицательным, имел F>=1.

Если хотя бы одно из вышеперечисленных условий или оба не выполнены, SQLite использует традиционную стратегию обработки ограничений IN поочерёдно. Если оба условия выполняются, то аргумент argvIndex к методу xFilter будет значением sqlite3_value, которое, кажется, равно NULL, но может быть передано в sqlite3_vtab_in_first() и sqlite3_vtab_in_next() для поиска всех значений в правой части ограничения IN.

См. также списки Объектов, Констант и Функций.