svySearch
Welcome to the svySearch wiki! This wiki provides comprehensive documentation to using the svySearch module. This module is designed to parse natural-language text input and apply it to developer-specified patterns for searching.
Table of Contents
Parsing Rules
Text is parsed according to some general patterns. String fragments are matched against developer-specified SearchProvider, which map some rules to how certain columns are searched.
Patterns
Tokens: Parsing input for individual words
Quoted Strings: Used to escape token separators
Aliases: Used to explicitly referenes a single SearchProvider
Operators: For comparisons other than the default LIKE/Contains
Substitutions: Dynamically match and replace input text, ideal for converting value list values into stored values
Tokens
Words separated by white space will be treated as separate tokens. ALL tokens must match ANY SearchProvider.
Example
NOTE: Multiple tokens that match on the same related SearchProvider are not currently supported and may result in no records. This cannot be easily supported, because when a SearchProvider is compared to multiple tokens, we cannot know which token(s) matched, and therefore, cannot guarantee the contract for matching ALL tokens.
Quoted Strings
Use double quotes to escape tokenization
Example
Aliases
Any SearchProvider can be explicitly searched using the data provider name or alias. Aliases are specified left or a ':' character. Additionally, some SearchProvider can be specified as explicit-only, meaning the field is not searched unless the user performs an alias-based search. This can be useful for date fields
Example
Operators
By default, all searches are LIKE/Contains for Strings and strict "=" for Numbers and Dates. However, additional operators may be specified at the beginning of a token (except for the BETWEEN operator)
Operator | Name | Summary |
---|---|---|
- | Exclude | Excludes the token from the search using a NOT LIKE for Strings and NOT EQUAL for Numbers and Dates |
+ | Exact | Performs an exact match in lieu of a LIKE |
> | Greater-Than | Matches all values greater than the specified token |
>= | Greater-Than-Or-Equal | Matches all values greater than or equal to the specified token |
< | Less-Than | Matches all values less than the specified token |
<= | Less-Than-Or-Equal | Matches all values less than or equal to the specified token |
... | Between | Matches all values between the two operands |
Example
Substitutions
Substitutions can be applied dynamically to match and replace string fragments within user input. This is ideal for allowing users to express custom ValueList display values in their searches, and have those values resolved to the actual stored/DB value
Example
API Documentation
svySearch is an object-oriented API for parsing user input and applying searches against the data model.
The API consists of the primary class SimpleSearch, which models a search on a particular data source and its supporting class, SearchProvider, which models th ecomponent of the search that maps to a single data provider.
Example
svySearch
A single scope that contains the classes
Method Summary
createSimpleSearch
Params
Type | Name | Summary | Required |
---|---|---|---|
Number | dataSource | The data source used | Required |
returns
example
SimpleSearch
A class which models a search on a particular data source and its supporting class
Method Summary
Return Type | Method | Description |
---|---|---|
Add alternative date format which is used to parse user input for searching dates in addition to the default format. | ||
Adds a dataprovider to the search object. | ||
Get all search providers for this search object | ||
Returns the alternate date format which is used to parse user input for searching dates in addition to the default format. | ||
Returns the data source used by the search object | ||
Returns the date format which is used to parse user input for searching dates | ||
Creates a factory foundset, runs the search and returns it | ||
Creates and returns a query object parsed from the user input | ||
Gets the raw, unparsed input text | ||
Loads records on the specified foundset. | ||
Remove alternative date format which is used to parse user input for searching dates in addition to the default format. | ||
Sets the date formatting which will be used to parse user input | ||
Sets that all columns are to be searchable | ||
Set the raw, user input to be parsed |
Method Details
addAlternateDateFormat
Add alternative date format which is used to parse user input for searching dates in addition to the default format.
Params
Type | Name | Summary | Required |
---|---|---|---|
format | any date format pattern that will result in a well defined time interval to search for (e.g. MM-yyyy will look for beginning of month to end of month) | Required |
Returns SimpleSearch
Example
addSearchProvider
Adds a search provider to the search object.
Params
Type | Name | Summary | Required |
---|---|---|---|
dataProviderID | The data provider that will be searched. Can be columns, related columns | Required | |
alias | The natural language name of the search provider. Used in explicit searches. | Optional. Default is same as data provider | |
impliedSearch | Set this false to indicate that a provider is not searchable unless explicitly referenced | Optional. Default is True | |
caseSensitive | Set this to be true to force case-sensitive search on this search provider | Optional. Default is False |
Returns SearchProvider
getAllSearchProviders
Get all search providers for this search object
Returns Array<SearchProvider>
getAlternateDateFormats
Returns the alternate date format which is used to parse user input for searching dates in addition to the default format.
Returns Array<String>
getDataSet
Executes the search and returns the results as a JSDataSet
Params
Type | Name | Summary | Required |
---|---|---|---|
Number | maxRows | The max rows to retrieve | Optional. Default is -1 (unlimited) |
Returns JSDataSet
getDataSource
Returns the data source used by the search object
Returns String
getDateFormat
Returns the date format which is used to parse user input for searching dates
Returns String
getFoundSet
Creates a factory foundset, runs the search and returns it
Returns JSFoundSet
getQuery
Creates and returns a query object parsed from the user input
Returns QBSelect
getSearchProvider
Gets the specified SearchProvider
Params
Type | Name | Summary | Required |
---|---|---|---|
aliasOrDataProvider | The name or alias of the data provider | Required |
Returns SearchProvider or null if named SearchProvider is not found
getSearchText
Gets the raw, unparsed input text
Returns String
loadRecords
Loads records in the specified foundset
Params
Type | Name | Summary | Required |
---|---|---|---|
foundSet | Required |
Returns Boolean True indicates query was successful, although may have loaded zero records
removeAlternateDateFormat
Remove alternative date format which is used to parse user input for searching dates in addition to the default format.
Params
Type | Name | Summary | Required |
---|---|---|---|
format | the alternate date format to be removed | Required |
Returns SimpleSearch
setDateFormat
Sets the date formatting which will be used to parse user input
Params
Type | Name | Summary | Required |
---|---|---|---|
format | The format to use for date searches | Required |
Returns SimpleSearch Returns this SimpleSearch for convenience, method chaining
setSearchAllColumns
Sets that all columns are to be searchable
This should be called before adding any additional, related search providers
Returns SimpleSearch Returns this SimpleSearch for convenience, method chaining
setSearchText
Set the raw, user input to be parsed
Params
Type | Name | Summary | Required |
---|---|---|---|
searchText | The raw text to be parsed | Required |
Returns SimpleSearch Returns this SimpleSearch for convenience, method chaining
A class which models the component of the search that maps to a single data provider.
Method Summary
Return Type | Method | Description |
---|---|---|
Add a substitution kev-value pair to this search provider | ||
Gets the alias of this search provider. | ||
Gets the data provider ID | ||
JSColumn | Get the JSColumn object that corresponds to this search provider | |
JSTable | Get the JSTable object that corresponds to this search provider | |
Get all the keys for substitutions | ||
Get the substitution value for a given key | ||
Specifies if this search provider is included in implied search | ||
Method Details
addSubstitution
Add a substitution kev-value pair to this search provider
Substitutions provide replacement capability for user input.
A typical use case involves parsing a value list display value
Params
Type | Name | Summary | Required |
---|---|---|---|
key | A string to be replaced | Required | |
value | The value to replace it with | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining
getAlias
Gets the alias of this search provider.
Returns String The alias, or null if none was specified
getDataProviderID
Gets the data provider ID
Returns String The data provider which will be searched
getJSColumn
Get the JSColumn object that corresponds to this search provider
Returns JSColumn
getJSTable
Get the JSTable object that corresponds to this search provider
Returns JSTable
getStringMatching
Get the matching mode for this search provider.
Returns String
getSubstitutionsKeys
Get all the keys for substitutions
getSubstitutionValue
Get the substitution value for a given key
Params
Type | Name | Summary | Required |
---|---|---|---|
key | The substitution key | Required |
Returns String
isCaseSensitive
Indicates if this SearchProvider is case-sensitive
Returns Boolean
isCastInteger
Indicates if this SearchProvider will cast INTEGER values to TEXT in the query
Returns [Boolean]
isImpliedSearch
Indicates if this SearchProvider is an implied search
Returns Boolean
setAlias
Sets the natural language name for this SearchProvider
The alias can be used in explicit searches
Params
Type | Name | Summary | Required |
---|---|---|---|
alias | The alias | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining
setCaseSensitive
Specifies if this SearchProvider will perform case-sensitive searches
Params
Type | Name | Summary | Required |
---|---|---|---|
caseSensitive | The value for case-sensitive | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining
setCastInteger
Specifies if this SearchProvider will cast INTEGER values to TEXT in the query. For example, a search term "1025"
would match on 10250
, 10251
, 91025
, etc.
Params