Табличная функция Carray()

1. Обзор

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

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

Начиная с версии SQLite 3.51.0 (2025-11-04), расширение carray() входит в состав амальгамации, однако по умолчанию отключено и не работает, если SQLite не скомпилирована с параметром -DSQLITE_ENABLE_CARRAY. До версии 3.51.0 carray() находилась в отдельном исходном файле, который требовалось скомпилировать независимо, а затем добавить в SQLite как загружаемое расширение.

Функция 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() принимает один, два или три аргумента. Рекомендуется использовать вариант с одним аргументом.

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 SQLITE_CARRAY_INT32   0
  #define SQLITE_CARRAY_INT64   1
  #define SQLITE_CARRAY_DOUBLE  2
  #define SQLITE_CARRAY_TEXT    3
  #define SQLITE_CARRAY_BLOB    4

Тип SQLITE_CARRAY_INT32 означает, что массив состоит из элементов типа "int". SQLITE_CARRAY_INT64 означает, что массив состоит из элементов типа "sqlite3_int64". Аргумент SQLITE_CARRAY_DOUBLE означает, что массив состоит из элементов типа "double". SQLITE_CARRAY_TEXT означает, что массив состоит из элементов типа "char*", где каждый элемент массива является либо указателем NULL, либо указателем на строку, завершающуюся нулевым символом.

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

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

На данный момент все старшие биты параметра mFlags должны быть нулевыми, хотя они могут использоваться в будущих расширениях.

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

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

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

3.2. CARRAY с несколькими аргументами

В исходной версии carray() использовалось два или три аргумента. Этот способ по-прежнему поддерживается для обратной совместимости, однако новым приложениям рекомендуется использовать описанную выше форму carray() с одним аргументом.

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

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

Тип данных по умолчанию — 'int32'. Если функция carray() принимает только два аргумента, предполагается тип данных 'int32'.

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

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

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

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

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

Эта страница была обновлена 2026-01-26 15:45:07Z