Функция CARRAY() со значениями таблицы

1. Обзор

Функция carray() — это функция со значениями таблицы с одним столбцом (названным "value") и нулем или более строками. Значение каждой строки в carray() берется из массива языка C, предоставленного приложением через связывание параметров. Таким образом, функция carray() предоставляет удобный механизм для связывания массивов языка C с SQL-запросами.

2. Доступность

Функция carray() по умолчанию не компилируется в SQLite. Она доступна как загружаемый модуль в файле исходного кода загружаемого модуля ext/misc/carray.c.

Функция carray() была впервые добавлена в SQLite в версии 3.14 (2016-08-08). Интерфейс sqlite3_carray_bind() и одноаргументный вариант carray() были добавлены в SQLite версии 3.34.0 (2020-12-01). Возможность связывания массива struct iovec объектов, интерпретируемых как BLOB, была добавлена в SQLite версии 3.41.0 (2023-02-21).

3. Детали

Функция carray() принимает один, два или три аргумента.

Для дву- и трехаргументных вариантов carray() первый аргумент — указатель на массив. Поскольку значения указателей нельзя указать непосредственно в SQL, первый аргумент должен быть параметром, который связан со значением указателя с использованием интерфейса sqlite3_bind_pointer() с типом указателя "carray". Второй аргумент — количество элементов в массиве. Необязательный третий аргумент — строка, определяющая тип данных элементов в массиве языка C. Допустимые значения для третьего аргумента:

1. 'int32'
2. 'int64'
3. 'double'
4. 'char*'
5. 'struct iovec'

По умолчанию тип данных — 'int32'.

Тип 'struct iovec', используемый для данных BLOB, — это стандартная структура данных Posix, обычно объявляемая с помощью "#include <sys/uio.h>". Формат:

struct iovec {
  void  *iov_base; /* Starting address */
  size_t iov_len;  /* Number of bytes to transfer */
};

3.1. Одноаргументная CARRAY

Одноаргументная форма carray() требует специального интерфейса языка C под названием "sqlite3_carray_bind()" для подключения значений:

  int sqlite3_carray_bind(
    sqlite3_stmt *pStmt,         /* Statement containing the CARRAY */
    int idx,                     /* Parameter number for CARRAY argument */
    void *aData,                 /* Data array */
    int nData,                   /* Number of entries in the array */
    int mFlags,                  /* Datatype flag */
    void (*xDestroy)(void*)      /* Destructor for aData */
  );

Параметр mFlags для sqlite3_carray_bind() должен быть одним из следующих:

  #define CARRAY_INT32   0
  #define CARRAY_INT64   1
  #define CARRAY_DOUBLE  2
  #define CARRAY_TEXT    3
  #define CARRAY_BLOB    4

В настоящее время все старшие биты параметра mFlags должны быть равны нулю, хотя они могут быть использованы в будущих усовершенствованиях. Определения констант, которые указывают тип данных, и прототип функции sqlite3_carray_bind() доступны в дополнительном заголовочном файле ext/misc/carray.h.

Аргумент xDestroy для sqlite3_carray_bind() — указатель на функцию, которая освобождает входной массив. SQLite вызовет эту функцию после завершения работы с данными. Аргумент xDestroy может необязательно быть одной из следующих констант, определенных в "sqlite3.h":

• SQLITE_STATIC → Это означает, что приложение, которое вызывает sqlite3_carray_bind(), сохраняет владение массивом данных и гарантирует SQLite, что оно не будет изменять или освобождать данные до завершения подготовки оператора.

• SQLITE_TRANSIENT → Это специальное значение сообщает SQLite создать свою собственную копию данных до возвращения интерфейса sqlite3_carray_bind().

4. Использование

Функция carray() может использоваться в разделе FROM запроса. Например, для запроса двух записей из таблицы OBJ, используя идентификаторы строк, взятые из массива языка C по адресу $PTR.

SELECT obj.* FROM obj, carray($PTR, 10) AS x
 WHERE obj.rowid=x.value;

Этот запрос дает тот же результат:

SELECT * FROM obj WHERE rowid IN carray($PTR, 10);

Эта страница была в последний раз изменена 17 февраля 2023 г. в 13:24:09 по UTC