Skip to main content

%iKnow.Filters.Filter

deprecated abstract class %iKnow.Filters.Filter extends %Library.RegisteredObject

This is the base class for iKnow Filter objects, restricting the scope of an iKnow Query to a subset of all the sources in a domain through filter criteria based on the properties of a Source. These criteria are expressed through a number of Filter Parameters which should be passed as arguments to the %New() method when instantiating a filter object. Typically, the first Filter Parameter is the Domain ID of the domain of which sources are to be filtered.

Filters have a String Representation so they can be passed around in non-object environments such as SQL and SOAP. Subclasses should therefore provide an unambiguous implementation for ToString(), serializing its Filter Parameters so the string can be passed around and then deserialized through the RestoreFilterFromString() method. See also CreateAsString() and %iKnow.Filters.FilterWSAPI for handling filters in non-COS environments.

Subclasses should provide an implementation for (at least) BuildSourceFilter(), building a bitstring with 1s for those Source IDs satisfying the filter criteria the filter class represents. In their %OnNew() implementation, subclasses should make sure to set the DomainId property and call Initialize() after setting all other properties specific to its implementation that influence the outcome of its ToString().

Filters can be cached so their calculated bitstrings can be reused (as long as they are still valid) across processes and time. Cache usage can be configured either by setting the $$$IKPENABLEFILTERCACHE domain parameter, or through a subclass explicitly enabling or disabling it when calling Initialize().

Sample Filter implementations include %iKnow.Filters.ExternalIdFilter, %iKnow.Filters.SentenceCountFilter and %iKnow.Filters.SimpleMetadataFilter

WARNING: When implementing a custom filter class, either make its properties read-only, or override the corresponding Set methods to call ChangeParams() to reset the internal representations after property values change. When setting these updateable properties in the class' %OnNew() method, use i% syntax to bypass these setters.

Property Inventory

Method Inventory

Properties

property DomainId as %Integer [ Final ];
The domain ID this filter instance is targeting.
Property methods: DomainIdDisplayToLogical(), DomainIdGet(), DomainIdIsValid(), DomainIdLogicalToDisplay(), DomainIdNormalize()
property FilteredSourceCount as %Integer [ InitialExpression = -1 , ReadOnly ];

The total number of sources satisfying this filter instances criteria.

This property is used to choose the fastest access path in iKnow Query implementations.

Property methods: FilteredSourceCountDisplayToLogical(), FilteredSourceCountIsValid(), FilteredSourceCountLogicalToDisplay(), FilteredSourceCountNormalize()
property IsCached as %Integer [ Final , InitialExpression = -1 , ReadOnly ];
Whether or not this filter instance is stored in the persistent cache.
Property methods: IsCachedDisplayToLogical(), IsCachedGet(), IsCachedIsValid(), IsCachedLogicalToDisplay(), IsCachedNormalize()
property Selectivity as %Numeric [ InitialExpression = -1 , ReadOnly ];

The ratio of sources satisfying this filter instances criteria to the total number of sources in this domain.

This property is used to choose the fastest access path in iKnow Query implementations.

Property methods: SelectivityDisplayToLogical(), SelectivityIsValid(), SelectivityLogicalToDisplay(), SelectivityNormalize()

Methods

method CheckResultCache(pQueryClass As %String, pQueryName As %String, pParams As %List, pPage As %Integer, pPageSize As %Integer, Output pIsCached, Output pResult) as %Status
pParams has empty positions for the pPage and pPageSize parameters Only use for queries without ByRef or Output parameters (except pResult) !!
method CheckResultCacheSingle(pQueryClass As %String, pQueryName As %String, pParams As %List, Output pIsCached, Output pResult) as %Status
Same as CheckResultCache(), but for single-result queries Only use for queries without ByRef or Output parameters !!
final classmethod ClearCachedFilter(domainId As %Integer, filterId As %Integer) as %Status [ SQLProc = Filter_ClearCachedFilter ]
Projected as the stored procedure: Filter_ClearCachedFilter

Clears a specific filter from the persistent filter cache, if it exists.

final classmethod ClearCachedFilters(domainId As %Integer) as %Status [ SQLProc = Filter_ClearCachedFilters ]
Projected as the stored procedure: Filter_ClearCachedFilters

Clears all filters from the persistent filter cache.

final classmethod CreateAsString(createParams...) as %String [ SQLProc = Filter_CreateAsString ]
Projected as the stored procedure: Filter_CreateAsString

This class method is an access point to generate the string representation (as specified in ToString()) for %iKnow.Filters.Filter classes, accessible from COS and SQL scenarios that cannot or prefer not to directly instantiate objects through COS.

When calling this method, you should supply the Filter Parameters as if calling the %New() method of this particular Filter implementation.

For Web Service scenario's, use the corresponding method in %iKnow.Filters.FilterWSAPI.

classmethod CreateFromBitstring(pDomainId As %Integer, ByRef pBitstring) as %iKnow.Filters.Filter
final classmethod CreateGroupAsString(domainId As %Integer, groupLogic As %Integer = $$$GROUPFILTERAND, negated As %Boolean = 0, filters...) as %String [ SQLProc = Filter_CreateGroupAsString ]
Projected as the stored procedure: Filter_CreateGroupAsString

This class enables SQL users to create the string representation of a %iKnow.Filters.GroupFilter composed of multiple subfilters passed in using their respective string representations as the filters... parameter.

For Web Service scenario's, use the corresponding method in %iKnow.Filters.FilterWSAPI.

classmethod FromString(pDomainId As %String, pString As %String, Output pFilter As %iKnow.Filters.Filter) as %Status

Converts the supplied string pString into a %iKnow.Filters.Filter object. In addition to the normal RestoreFilterFromString() functionality (which expects pString to be the output of a ToString() call on a filter object), this method supports the following shorthands:

Note: while covering a majority of common filter operations, the shorthand syntax is meant to simplify exploration through the command-line and does not handle every possible combination of parameters. Application code should therefore always use regular filter constructor methods and the string representations produced by ToString() (which this method also accepts).

final method GetCRCOccurrenceFilter(offset As %Integer) as %String

Returns a bitstring on crcOccIDs, representing those CRC occurrences appearing in a source satisfying the filter criteria.

final method GetCRCUniqueFilter(offset As %Integer) as %String

Returns a bitstring on crcUniIDs, representing those unique CRCs appearing in at least one source satisfying the filter criteria.

final method GetCcUniqueFilter(offset As %Integer) as %String

Returns a bitstring on crcUniIDs, representing those unique CCs appearing in at least one source satisfying the filter criteria.

final method GetEntityOccurrenceFilter(offset As %Integer) as %String

Returns a bitstring on entOccIDs, representing those entity occurrences appearing in a source source satisfying the filter criteria.

final method GetEntityUniqueFilter(offset As %Integer) as %String

Returns a bitstring on entUniIDs, representing those unique entities appearing in at least one source satisfying the filter criteria.

method GetFilteredCcFrequency(ccUniId As %Integer, type As %Integer = $$$IKFCCUNI) as %Integer

Returns the total frequency of a CC in the sources satisfying this filter instances criteria.

method GetFilteredCcSpread(ccUniId As %Integer, type As %Integer = $$$IKFCCUNI) as %Integer

Returns the total number of sources satisfying this filter instances criteria in which the supplied CC appears.

method GetFilteredCrcFrequency(crcUniId As %Integer) as %Integer

Returns the total frequency of a CRC in the sources satisfying this filter instances criteria.

method GetFilteredCrcSpread(crcUniId As %Integer) as %Integer

Returns the total number of sources satisfying this filter instances criteria in which the supplied CRC appears.

method GetFilteredEntityFrequency(entUniId As %Integer, role As %Integer = $$$ENTTYPEANY) as %Integer

Returns the total frequency of an entity in the sources satisfying this filter instances criteria, where the entities role is concept (if role = $$$ENTTYPECONCEPT), relation (if role = $$$ENTTYPERELATION) or either of the two (if role = $$$ENTTYPEANY).

method GetFilteredEntitySpread(entUniId As %Integer, role As %Integer = $$$ENTTYPEANY, details As %List = "") as %Integer

Returns the total number of sources in which the supplied entity appears that satisfy this filter instances criteria, where its role is concept (if role = $$$ENTTYPECONCEPT), relation (if role = $$$ENTTYPERELATION) or either of the two (if role = $$$ENTTYPEANY).

final method GetFilteredEntityUniqueCount(ByRef approximate As %Boolean = 0) as %Integer

Returns the total number of distinct entities occurring in at least one of the sources satisfying this filter instances criteria.

This property is used to choose the fastest access path in iKnow Query implementations.

method GetFilteredStemFrequency(pStemUniId As %Integer, pRole As %Integer = $$$ENTTYPEANY) as %Integer

Returns the total frequency of a stem in the sources satisfying this filter instances criteria, where the stem's role is concept (if pRole = $$$ENTTYPECONCEPT), relation (if pRole = $$$ENTTYPERELATION) or either of the two (if pRole = $$$ENTTYPEANY).

method GetFilteredStemSpread(pStemUniId As %Integer, pRole As %Integer = $$$ENTTYPEANY, details As %List = "") as %Integer

Returns the total number of sources in which the supplied stem appears that satisfy this filter instances criteria, where its role is concept (if pRole = $$$ENTTYPECONCEPT), relation (if pRole = $$$ENTTYPERELATION) or either of the two (if pRole = $$$ENTTYPEANY).

method GetFirstFilteredSource(direction As %Integer = 1) as %Integer

Returns the first Source ID satisfying this filter isntances criteria, starting from the lowest (direction 1) or highest Source ID (direction -1). Returns "" when no source is filtered.

method GetLabel() as %String
Utility method to return a label for this filter instance. Custom filter classes may override this method to return a nicer label in client applications.
final method GetNextCRCOccurrenceFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on CRC occurrence IDs.

final method GetNextCRCUniqueFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on unique CRC IDs.

final method GetNextCcUniqueFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on unique CC IDs.

final method GetNextEntityOccurrenceFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on entity occurrence IDs.

final method GetNextEntityUniqueFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on unique entity IDs.

final method GetNextPathFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on path IDs.

method GetNextSourceFilterOffset(offset As %Integer = "", Output nextBits As %Integer, direction As %Integer = 1) as %Integer

Retrieves a bitstring representing the Source IDs satisfying this Filters criteria, for the offset (sourceId\64000+1) following the supplied one. The returned number is the next offset (given the direction).

method GetNextSrcId(pSrcId As %Integer) as %Integer
final method GetPathFilter(offset As %Integer) as %String

Returns a bitstring on path IDs, representing those paths appearing in a source satisfying the filter criteria.

final method GetSourceFilter(offset As %Integer) as %String

Returns a bitstring representing the Source IDs satisfying this Filters criteria, for the given offset (sourceId\64000+1).

method Initialize(useCache As %Integer = -1) as %Status

This method initializes the data structures this Filter object will be using througout its lifetime as an object instance. If caching is enabled for this object (useCache = 1), it will check if there is already a cached entry corresponding to these filter criteria it can reuse, or create a new cache entry otherwise. If caching is disabled (useCache = 0), Process-Private Globals will be used for storing this filter instances internals and nothing will be reused. If useCache = -1 (default), the domain default will be used (set through the $$$IKPENABLEFILTERCACHE domain parameter).

method Invalidate(type As %Integer = $$$IKFSOURCE) as %Status

Resets all internal representations, forcing further use of this filter to recalculate results. If a type is supplied, only the bitstrings of that type are reset, including dependent ones. In the case of Source IDs (type = $$$IKFSOURCE), specific offset values can be invalidated separately.

method IsFiltered(id As %Integer, type As %Integer = $$$IKFSOURCE) as %Boolean

Returns whether the id of the given type appears in any source satisfying this filter instances criteria.

method IsValid(type As %Integer = $$$IKFSOURCE) as %Boolean

Checks if this filter for type is still up-to-date with regards to incorporating the most recent source additions and changes. Subclasses might wish to override this method but should combine their additional checks with the result of this root implementation if they do.

If the requested filter is not calculated, this method will return 0.

final classmethod RestoreFilterFromId(domainId As %Integer, filterId As %Integer) as %iKnow.Filters.Filter

Utility method to restore a cached filter based on its cached filter ID.

final classmethod RestoreFilterFromString(filterSpec As %String) as %iKnow.Filters.Filter

Utility method to recreate a filter based on its string representation, which by default corresponds to the filter class name, a pipe character (|) and a filter-specific string containing all parameters required to recreate the string using the %New() method. Subclasses should override RestoreFilterFromStringInternal() if this default behavior is not sufficient.

This method is used primarily in SQL and Web Service scenarios, where the filter objects themselves cannot be passed in a SQL statement or SOAP request.

method StoreResultCache(pQueryClass As %String, pQueryName As %String, pParams As %List, pPage As %Integer, pPageSize As %Integer, ByRef pResult) as %Status
method StoreResultCacheSingle(pQueryClass As %String, pQueryName As %String, pParams As %List, pResult) as %Status
abstract method ToString() as %String

Subclasses should implement this method to build a string representation of the filter instance. It should start with the filter class name, followed by a pipe (|) character and then a string representation that can be interpreted by its RestoreFilterFromStringInternal() implementation.

Inherited Members

Inherited Methods

Subclasses

FeedbackOpens in a new tab