1. Обзор

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

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

carray() не собрана в SQLite по умолчанию. Это доступно как загружаемое расширение в файле ext/misc/carray.c.

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

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, используя rowid взятый из массива на 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);