xref: /netbsd-src/external/public-domain/sqlite/man/sqlite3_vtab_rhs_value.3 (revision b9988867a8ad969c45a52aa7628bc932ec98d46b)
1.Dd January 24, 2024
2.Dt SQLITE3_VTAB_RHS_VALUE 3
3.Os
4.Sh NAME
5.Nm sqlite3_vtab_rhs_value
6.Nd constraint values in xBestIndex()
7.Sh SYNOPSIS
8.In sqlite3.h
9.Ft int
10.Fo sqlite3_vtab_rhs_value
11.Fa "sqlite3_index_info*"
12.Fa "int"
13.Fa "sqlite3_value **ppVal"
14.Fc
15.Sh DESCRIPTION
16This API may only be used from within the xBestIndex method
17of a virtual table implementation.
18The result of calling this interface from outside of an xBestIndex
19method are undefined and probably harmful.
20.Pp
21When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
22the xBestIndex method of a virtual table implementation,
23with P being a copy of the sqlite3_index_info object
24pointer passed into xBestIndex and J being a 0-based index into P->aConstraint[],
25then this routine attempts to set *V to the value of the right-hand
26operand of that constraint if the right-hand operand is known.
27If the right-hand operand is not known, then *V is set to a NULL pointer.
28The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if and
29only if *V is set to a value.
30The sqlite3_vtab_rhs_value(P,J,V) inteface returns SQLITE_NOTFOUND
31if the right-hand side of the J-th constraint is not available.
32The sqlite3_vtab_rhs_value() interface can return an result code other
33than SQLITE_OK or SQLITE_NOTFOUND if something goes wrong.
34.Pp
35The sqlite3_vtab_rhs_value() interface is usually only successful if
36the right-hand operand of a constraint is a literal value in the original
37SQL statement.
38If the right-hand operand is an expression or a reference to some other
39column or a host parameter, then sqlite3_vtab_rhs_value()
40will probably return SQLITE_NOTFOUND.
41.Pp
42Some constraints, such as SQLITE_INDEX_CONSTRAINT_ISNULL
43and SQLITE_INDEX_CONSTRAINT_ISNOTNULL,
44have no right-hand operand.
45For such constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.
46.Pp
47The sqlite3_value object returned in *V is a protected
48sqlite3_value and remains valid for the duration of the xBestIndex
49method call.
50When xBestIndex returns, the sqlite3_value object returned by sqlite3_vtab_rhs_value()
51is automatically deallocated.
52.Pp
53The "_rhs_" in the name of this routine is an abbreviation for "Right-Hand
54Side".
55.Sh IMPLEMENTATION NOTES
56These declarations were extracted from the
57interface documentation at line 10083.
58.Bd -literal
59SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);
60.Ed
61.Sh SEE ALSO
62.Xr sqlite3_bind_blob 3 ,
63.Xr sqlite3_index_info 3 ,
64.Xr sqlite3_value 3 ,
65.Xr SQLITE_INDEX_CONSTRAINT_EQ 3 ,
66.Xr SQLITE_OK 3
67