%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> xwhere <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 standard bitmap index. 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
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
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
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 standard index type, 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 SQL 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
For a given chunk number pChunk, return the corresponding actual bitmap string.
This method must be implemented when %FIND is used.
This method simulates the usage of
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.
This method simulates the usage of
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
- %AddToSaveSet()
- %ClassIsLatestVersion()
- %ClassName()
- %ConstructClone()
- %DispatchClassMethod()
- %DispatchGetModified()
- %DispatchGetProperty()
- %DispatchMethod()
- %DispatchSetModified()
- %DispatchSetMultidimProperty()
- %DispatchSetProperty()
- %Extends()
- %GetParameter()
- %IsA()
- %IsModified()
- %New()
- %NormalizeObject()
- %ObjectModified()
- %OriginalNamespace()
- %PackageName()
- %RemoveFromSaveSet()
- %SerializeObject()
- %SetModified()
- %ValidateObject()