Index: third_party/sqlite/src/ext/fts5/fts5.h |
diff --git a/third_party/sqlite/src/ext/fts5/fts5.h b/third_party/sqlite/src/ext/fts5/fts5.h |
index 5f528af7933fce0bfc527ac55e9548b63d447a15..a45c145d38b9ca86cd515c07f439e3c7f32a4eeb 100644 |
--- a/third_party/sqlite/src/ext/fts5/fts5.h |
+++ b/third_party/sqlite/src/ext/fts5/fts5.h |
@@ -84,6 +84,9 @@ struct Fts5PhraseIter { |
** an OOM condition or IO error), an appropriate SQLite error code is |
** returned. |
** |
+** This function may be quite inefficient if used with an FTS5 table |
+** created with the "columnsize=0" option. |
+** |
** xColumnText: |
** This function attempts to retrieve the text of column iCol of the |
** current document. If successful, (*pz) is set to point to a buffer |
@@ -104,15 +107,29 @@ struct Fts5PhraseIter { |
** the query within the current row. Return SQLITE_OK if successful, or |
** an error code (i.e. SQLITE_NOMEM) if an error occurs. |
** |
+** This API can be quite slow if used with an FTS5 table created with the |
+** "detail=none" or "detail=column" option. If the FTS5 table is created |
+** with either "detail=none" or "detail=column" and "content=" option |
+** (i.e. if it is a contentless table), then this API always returns 0. |
+** |
** xInst: |
** Query for the details of phrase match iIdx within the current row. |
** Phrase matches are numbered starting from zero, so the iIdx argument |
** should be greater than or equal to zero and smaller than the value |
** output by xInstCount(). |
** |
+** Usually, output parameter *piPhrase is set to the phrase number, *piCol |
+** to the column in which it occurs and *piOff the token offset of the |
+** first token of the phrase. The exception is if the table was created |
+** with the offsets=0 option specified. In this case *piOff is always |
+** set to -1. |
+** |
** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) |
** if an error occurs. |
** |
+** This API can be quite slow if used with an FTS5 table created with the |
+** "detail=none" or "detail=column" option. |
+** |
** xRowid: |
** Returns the rowid of the current row. |
** |
@@ -126,11 +143,13 @@ struct Fts5PhraseIter { |
** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid |
** |
** with $p set to a phrase equivalent to the phrase iPhrase of the |
-** current query is executed. For each row visited, the callback function |
-** passed as the fourth argument is invoked. The context and API objects |
-** passed to the callback function may be used to access the properties of |
-** each matched row. Invoking Api.xUserData() returns a copy of the pointer |
-** passed as the third argument to pUserData. |
+** current query is executed. Any column filter that applies to |
+** phrase iPhrase of the current query is included in $p. For each |
+** row visited, the callback function passed as the fourth argument |
+** is invoked. The context and API objects passed to the callback |
+** function may be used to access the properties of each matched row. |
+** Invoking Api.xUserData() returns a copy of the pointer passed as |
+** the third argument to pUserData. |
** |
** If the callback function returns any value other than SQLITE_OK, the |
** query is abandoned and the xQueryPhrase function returns immediately. |
@@ -196,7 +215,7 @@ struct Fts5PhraseIter { |
** Fts5PhraseIter iter; |
** int iCol, iOff; |
** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); |
-** iOff>=0; |
+** iCol>=0; |
** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) |
** ){ |
** // An instance of phrase iPhrase at offset iOff of column iCol |
@@ -204,13 +223,51 @@ struct Fts5PhraseIter { |
** |
** The Fts5PhraseIter structure is defined above. Applications should not |
** modify this structure directly - it should only be used as shown above |
-** with the xPhraseFirst() and xPhraseNext() API methods. |
+** with the xPhraseFirst() and xPhraseNext() API methods (and by |
+** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below). |
+** |
+** This API can be quite slow if used with an FTS5 table created with the |
+** "detail=none" or "detail=column" option. If the FTS5 table is created |
+** with either "detail=none" or "detail=column" and "content=" option |
+** (i.e. if it is a contentless table), then this API always iterates |
+** through an empty set (all calls to xPhraseFirst() set iCol to -1). |
** |
** xPhraseNext() |
** See xPhraseFirst above. |
+** |
+** xPhraseFirstColumn() |
+** This function and xPhraseNextColumn() are similar to the xPhraseFirst() |
+** and xPhraseNext() APIs described above. The difference is that instead |
+** of iterating through all instances of a phrase in the current row, these |
+** APIs are used to iterate through the set of columns in the current row |
+** that contain one or more instances of a specified phrase. For example: |
+** |
+** Fts5PhraseIter iter; |
+** int iCol; |
+** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol); |
+** iCol>=0; |
+** pApi->xPhraseNextColumn(pFts, &iter, &iCol) |
+** ){ |
+** // Column iCol contains at least one instance of phrase iPhrase |
+** } |
+** |
+** This API can be quite slow if used with an FTS5 table created with the |
+** "detail=none" option. If the FTS5 table is created with either |
+** "detail=none" "content=" option (i.e. if it is a contentless table), |
+** then this API always iterates through an empty set (all calls to |
+** xPhraseFirstColumn() set iCol to -1). |
+** |
+** The information accessed using this API and its companion |
+** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext |
+** (or xInst/xInstCount). The chief advantage of this API is that it is |
+** significantly more efficient than those alternatives when used with |
+** "detail=column" tables. |
+** |
+** xPhraseNextColumn() |
+** See xPhraseFirstColumn above. |
*/ |
struct Fts5ExtensionApi { |
- int iVersion; /* Currently always set to 1 */ |
+ int iVersion; /* Currently always set to 3 */ |
void *(*xUserData)(Fts5Context*); |
@@ -240,8 +297,11 @@ struct Fts5ExtensionApi { |
int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); |
void *(*xGetAuxdata)(Fts5Context*, int bClear); |
- void (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); |
+ int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); |
void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); |
+ |
+ int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*); |
+ void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol); |
}; |
/* |
@@ -258,7 +318,7 @@ struct Fts5ExtensionApi { |
** behaviour. The structure methods are expected to function as follows: |
** |
** xCreate: |
-** This function is used to allocate and inititalize a tokenizer instance. |
+** This function is used to allocate and initialize a tokenizer instance. |
** A tokenizer instance is required to actually tokenize text. |
** |
** The first argument passed to this function is a copy of the (void*) |
@@ -517,4 +577,3 @@ struct fts5_api { |
#endif |
#endif /* _FTS5_H */ |
- |