Skip to main content

%SQL.AbstractFind

abstract class %SQL.AbstractFind extends %Library.RegisteredObject

%SQL.AbstractFind defines the interface used by the SQL %FIND and %INSET filter conditions.

SQL %FIND and other filters

SQL Filter Interface

Overview

This class defines the interface used for %FIND and %INSET SQL filter conditions, which use the following syntax:

    f <filter> x
where <filter> is either %FIND or %INSET, and x represents a set of values S used as a filter for f, or more precisely, the condition is satisfied iff f is a member of S.

x is an expression that evaluates at run-time to the oref of an object that provides an abstract representation encapsulating the set S of non-NULL values (often IDs), by implementing the interface specified in this class. This interface consists of methods called at query run-time, that represent S's contents. The interface differs based on which of the two filter conditions is used.

These conditions enable filtering using a given abstract, programmatically specified set of values, and in particular, enable filtering of the rowid field using an abstract, programmatically specified temp-file or bitmap index, where x behaves similarly to the last subscript layer of a bitmap index.

%INSET requires x to support the simplest and most general interface, consisting of the single method ContainsItem()(i), which returns 1 iff i is in the set.

This method must also be supported by x for %FIND.

%FIND requires x to support an interface that emulates a set S of positive integers as if being stored in a CacheSQL conventional bitmap layer. When t.%ID is used for f, this interface allows the query processor to use x in various capacities as if it were an index of t, including driving the processing of table t, or as part of a complex multi-index strategy for t.

In addition to ContainsItem(), the %FIND interface includes the three methods GetChunk(), NextChunk(), and PreviousChunk(), which emulate the usage of $ORDER()/$DATA() to access and iterate over bitmap chunks storing the set S of positive integer values, much the same way as a set of ID's is stored in a conventional CacheSQL bitmap index, where an item i in S corresponds to a single bit being on. More specifically, S can be considered stored in a sequence of bitmap chunks b of up to 64,000 bits each, each stored within an array under a subscripted positive integer chunk number c, say bm(c)=b, where for any positive integer i, i is in S iff $BIT(bm(i\64000+1),i#64000+1)=1 . Equivalently, $BIT(bm(c),p)=1 iff the integer (c-1)*64000+p-1 is in S.

The method GetChunk()(c) returns the bitmap chunk b corresponding with chunk number c, if there is any ("" otherwise), with bit positions 1 to 64000 within b representing which of the integers (c-1)*64000 to c*64000-1 are or are not in S.

The methods NextChunk()(.c) and PreviousChunk()(.c) project a sequence of ordered (but not necessarily consecutive) chunk numbers c, each with its corresponding bitmap chunk b of up to 64000 bits. The chunk number .c is input/output, proceeding in order starting and ending with "", exactly as in $ORDER(). When the returned .c is non-NULL, then the method return value is b, the bitmap chunk itself.

Note that it's OK for the returned bitmap chunk b to have no bits set to 1, including b="" , even when the returned c is not NULL, just as when using $ORDER() to iterate over the bitmap layer of an actual CacheSQL bitmap index. On the other hand, it's also OK for the method implementation to skip such a chunk and proceed to the next c .

For the condtition (t.%ID %FIND x) to use this bitmap interface, t.%ID must be "bitmap-eligible", i.e. declared or implied to be a positive integer, and t must also have an extent bitmap index. If either of these does not hold, then %FIND is automatically "downgraded" to %INSET, i.e. only the x.ContainsItem() of the %INSET interface for x is used by the run-time query instead of the %FIND bitmap interface.

For example, a bitmap produced in a previous processing step, e.g. in a BI/OLAP or a report-generating context, can be used as an input filter for the next query by using this interface with %FIND.

As another example, for a given table, in order to support specialized algorithms for searching through geographic data, or to support specialized iKnow searches, one can imagine defining an abstract index, one that is not structured like a normal Cache/CacheSQL index, but rather defined programmatically. The search parameters could be specified in the query as part of the second argument of %FIND, in a call to a user-defined function which would compute the resulting set of rows, and which would return an object that represents that set by supporting the interface required by the query.

Note that all of the method calls are, in principle, "stateless" - no assumptions can be made regarding the order or sequence of these calls, and no internal "previous state" can affect the external behavior and the returned values of any method call. Of course in programming these methods internally one may optimize the internal behavior in any way, including maintaining an internal state (e.g. a cache), or anticipating certain call profiles.

For example, a class TempBitmap could be defined to store data in a PPG, in a bitmap structure similar to the temp-files normally produced by generated CacheSQL queries for storing just a list of IDs, e.g.:

    ^||%sql.bitmap(..loc,0,chunk#)=<bit-map>

The formal syntax for the filter condition is:

	<cond> ::= <scalx> <filter> <scalx> [ <sizehint> ]
	<filter> ::= %INSET | %FIND
	<sizehint> ::= SIZE <pconst>
	<pconst> ::= ( <pconst> ) | <const>

Method Inventory

Methods

method ContainsItem(pItem As %String) as %Boolean
At minimum, ContainsItem() must always be supported. It returns 1 iff the given pItem is in the set S.
method GetChunk(pChunk As %Integer) as %Binary

For a given chunk number pChunk, return the corresponding actual bitmap string.

This method must be implemented when %FIND is used.

method NextChunk(ByRef pChunk As %Integer = "") as %Binary

This method simulates the usage of $ORDER() to traverse through the chunks of a bitmap index or a bitmap temp-file that would represent the set S.

For a given chunk number pChunk, find the first chunk number > pChunk and return it in .pChunk, with the method return value being the corresponding actual bitmap string. Return .pChunk="" if none found.

Note that when returning a positive .pChunk, it's OK for the returned bitmap b to have no bits set to 1, including b="" . On the other hand, it's also OK for the method implementation to skip such a chunk and proceed to the next pChunk.

This method must be implemented when %FIND is used.

method PreviousChunk(ByRef pChunk As %Integer = "") as %Binary

This method simulates the usage of $ORDER() to traverse backwards through the chunks of a bitmap index or a bitmap temp-file that would represent the set S.

For a given chunk number pChunk, find the first chunk number < pChunk and return it in .pChunk, with the method return value being the corresponding actual bitmap string. Return .pChunk="" if none found.

Note that when returning a positive .pChunk, it's OK for the returned bitmap b to have no bits set to 1, including b="" . On the other hand, it's also OK for the method implementation to skip such a chunk and proceed to the next pChunk.

This method must be implemented when %FIND is used.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab