.Dd January 24, 2024
.Dt SQLITE3_VTAB_RHS_VALUE 3
.Os
.Sh NAME
.Nm sqlite3_vtab_rhs_value
.Nd constraint values in xBestIndex()
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_vtab_rhs_value
.Fa "sqlite3_index_info*"
.Fa "int"
.Fa "sqlite3_value **ppVal"
.Fc
.Sh DESCRIPTION
This API may only be used from within the xBestIndex method
of a virtual table implementation.
The result of calling this interface from outside of an xBestIndex
method are undefined and probably harmful.
.Pp
When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
the xBestIndex method of a virtual table implementation,
with P being a copy of the sqlite3_index_info object
pointer passed into xBestIndex and J being a 0-based index into P->aConstraint[],
then this routine attempts to set *V to the value of the right-hand
operand of that constraint if the right-hand operand is known.
If the right-hand operand is not known, then *V is set to a NULL pointer.
The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if and
only if *V is set to a value.
The sqlite3_vtab_rhs_value(P,J,V) inteface returns SQLITE_NOTFOUND
if the right-hand side of the J-th constraint is not available.
The sqlite3_vtab_rhs_value() interface can return an result code other
than SQLITE_OK or SQLITE_NOTFOUND if something goes wrong.
.Pp
The sqlite3_vtab_rhs_value() interface is usually only successful if
the right-hand operand of a constraint is a literal value in the original
SQL statement.
If the right-hand operand is an expression or a reference to some other
column or a host parameter, then sqlite3_vtab_rhs_value()
will probably return SQLITE_NOTFOUND.
.Pp
Some constraints, such as SQLITE_INDEX_CONSTRAINT_ISNULL
and SQLITE_INDEX_CONSTRAINT_ISNOTNULL,
have no right-hand operand.
For such constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.
.Pp
The sqlite3_value object returned in *V is a protected
sqlite3_value and remains valid for the duration of the xBestIndex
method call.
When xBestIndex returns, the sqlite3_value object returned by sqlite3_vtab_rhs_value()
is automatically deallocated.
.Pp
The "_rhs_" in the name of this routine is an abbreviation for "Right-Hand
Side".
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 10083.
.Bd -literal
SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);
.Ed
.Sh SEE ALSO
.Xr sqlite3_bind_blob 3 ,
.Xr sqlite3_index_info 3 ,
.Xr sqlite3_value 3 ,
.Xr SQLITE_INDEX_CONSTRAINT_EQ 3 ,
.Xr SQLITE_OK 3