Carray() 表值函數

1. 概述

Carray() 是一個表值函數，只有一個欄位（名為「value」）和零或多筆資料列。carray() 中每筆資料列的「value」取自應用程式透過參數繫結提供的 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 語言陣列中元素的資料類型。第三個參數允許的值為

'int32'
'int64'
'double'
'char*'
'struct iovec'

預設資料類型為 'int32'。

用於 BLOB 資料的 'struct iovec' 類型是一種標準的 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() 的單一引數形式需要一個名為 "sqlite3_carray_bind()" 的特殊 C 語言介面來附加值

  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 */
  );

傳遞給 sqlite3_carray_bind() 的 mFlags 參數必須為下列其中一個

  #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 中找到。

傳遞給 sqlite3_carray_bind() 常式的 xDestroy 引數是一個指向釋放輸入陣列的函式的指標。SQLite 在處理完資料後會呼叫此函式。xDestroy 引數可以選擇為 "sqlite3.h" 中定義的下列常數之一

SQLITE_STATIC → 這表示呼叫 sqlite3_carray_bind() 的應用程式維護資料陣列的所有權，且應用程式向 SQLite 承諾在準備好的陳述式完成之前不會變更或取消配置資料。
SQLITE_TRANSIENT → 此特殊值指示 SQLite 在 sqlite3_carray_bind() 介面傳回之前製作資料的私有副本。

4. 用法

carray() 函式可以用在查詢的 FROM 子句中。例如，使用從位址 $PTR 的 C 語言陣列取得 rowid 來查詢 OBJ 表中的兩個條目。

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

此查詢會得到相同的結果

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

此頁面最後修改於 2023-02-17 13:24:09 UTC