Carray() является табличной функцией с отдельным столбцом (названный значением") и нолем или больше строк. "Значение" каждой строки в carray() взято от множества языка C, поставляемого применением через параметр привязки. Таким образом carray() обеспечивает удобный механизм, чтобы связать множества языка C с SQL-запросами.
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.
Функция carray() берет один, два или три аргумента.
Для версии с двумя и тремя аргументами carray() первый аргумент это указатель на множество. Так как значения указателя не могут быть определены непосредственно в SQL, первый аргумент должен быть как параметр, который связан со значением указателя, используя интерфейс sqlite3_bind_pointer(), используя тип указателя "carray". Второй аргумент задает число элементов во множестве. Дополнительный третий аргумент это последовательность, которая определяет тип данных элементов во множестве языка C. Позволенные значения для третьего аргумента:
По умолчанию '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 */ };
Форма отдельного аргумента 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().
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);