%SQL.AbstractFind

Class %SQL.AbstractFind Extends %Library.RegisteredObject [ Abstract, System = 2 ]

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

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 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 $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 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 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 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> 

Methods

ContainsItem

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.

NextItem

Method NextItem(pItem As %String = "") As %String [ Internal ]

The NextItem, NextItemInclusive, PreviousItem, and PreviousItemInclusive methods are required when %INSUB is used. They emulate the usage of $ORDER() to iterate over the set of values S as if it was stored in a subscript, similar to a subscript layer in a regular index. The input parameter pItem and the returned item iterate in a sequence through all the elements of S, following the normal global subscript order ( "]]" ), starting and ending with "", exactly as $ORDER() does.

For a given pItem, return the first item > pItem

NextItemInclusive

Method NextItemInclusive(pItem As %String = "") As %String [ Internal ]

The NextItem, NextItemInclusive, PreviousItem, and PreviousItemInclusive methods are required when %INSUB is used.

For a given pItem, return the first item >= pItem

PreviousItem

Method PreviousItem(pItem As %String = "") As %String [ Internal ]

The NextItem, NextItemInclusive, PreviousItem, and PreviousItemInclusive methods are required when %INSUB is used.

For a given pItem, return the first item < pItem

PreviousItemInclusive

Method PreviousItemInclusive(pItem As %String = "") As %String [ Internal ]

The NextItem, NextItemInclusive, PreviousItem, and PreviousItemInclusive methods are required when %INSUB is used.

For a given pItem, return the first item <= pItem

NextChunk

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.

PreviousChunk

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.

GetChunk

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.

GetResult

Method GetResult() [ Internal ]

Copy all of the results into a process private global

%OnClose

Method %OnClose() As %Status [ Internal, Private, ServerOnly = 1 ]

This callback method is invoked by the %Close method to provide notification that the current object is being closed.

The return value of this method is ignored.

ResultContainsItem

ClassMethod ResultContainsItem(pResultID As %Integer, pItemID As %Binary) As %Boolean [ Internal ]

%OnNew

Method %OnNew() As %Status [ Internal, Private, ServerOnly = 1 ]

This callback method is invoked by the %New method to provide notification that a new instance of an object is being created.

If this method returns an error then the object will not be created.

It is passed the arguments provided in the %New call. When customizing this method, override the arguments with whatever variables and types you expect to receive from %New(). For example, if you're going to call %New, passing 2 arguments, %OnNew's signature could be:

Method %OnNew(dob as %Date = "", name as %Name = "") as %Status

If instead of returning a %Status code this method returns an oref and this oref is a subclass of the current class, then this oref will be the one returned to the caller of the %New method.