Home
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
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
Words separated by white space will be treated as separate tokens. ALL tokens must match ANY SearchProvider.
Example
John Smith // matches "John Smith", "Smithers Johnson", "John Doe" at "Smithefield Road", etc
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.
Use double quotes to escape tokenization
Example
"John Smith" // matches only "John Smith" and not "Smithers Johnson", "John Doe" at "Smithefield Road", etc
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
last-name:smith // matches "John Smith", but not John Doe at "Smithefield Road", etc.
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
john -smith // matches "John Doe" and "Suxy Johnson" but not "John Smith"
+john // matches "John Doe", but not "Suzy Johnson"
freight:>100 // matches any freight greater than $100
freight:>=100 // matches any freight greater or equal to $100
order-date:<01-01-1997 // matches any date less than 01-01-1997
order-date:<=01-01-1997 // matches any date less than or equal to 01-01-1997
order-date:01-01-1997...12-31-1997 // matches any date during the year of 1997
By default, for all search providers, text search will be non case-sensitive; for instance a search with text 'Servoy' will find a match for either 'SERVOY', 'sErVoy', 'servoy'. Each search provider can be configured to be case-sensitve or not ( see setCaseSensitive). Note that case-sensitive search will be performed using the UPPER function modifier; this can have a relevant impact on the perfomance of the search queries.
*New Case Sensitivity Default
Available since v2022.3.0
You can change the default behavior to be case-sensitive using the user property user.svy.search.defaultCaseSensitivity=true. The user property can be set in the user.properties setting of the admin-page or directly in the servoy.properties file used for the deployed Servoy instance.
user.svy.search.defaultCaseSensitivity=true
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
user-type:admin // where "admin" is substituted to some stored value, for example "1"
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
// create the search object
var search = scopes.svySearch.createSimpleSearch(foundset);
// add some data providers
search.addSearchProvider('shipcity');
// add related data providers
search.addSearchProvider('orders_to_customers.companyname');
search.addSearchProvider('orders_to_order_details.order_details_to_products.productname');
// add an explicit search provider
search.addSearchProvider('orderdate')
.setAlias('date')
.setImpliedSearch(false);
// set user input
search.setSearchText('germany ordered:01/01/1996');
// execute search in existing foundset
search.loadRecords(foundset);
A single scope that contains the classes
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| Number | dataSource | The data source used | Required |
returns
example
scopes.svySearch.createSimpleSearch(foundset);
scopes.svySearch.createSimpleSearch(record);
scopes.svySearch.createSimpleSearch('db:/example_data/orders');
A class which models a search on a particular data source and its supporting class
| Return Type | Method | Description |
|---|---|---|
| SimpleSearch | addAlternateDateFormat | Add alternative date format which is used to parse user input for searching dates in addition to the default format. |
| SearchProvider | addSearchProvider | Adds a dataprovider to the search object. |
| Array<SearchProvider> | getAllSearchProviders | Get all search providers for this search object |
| Array<String> | getAlternateDateFormats | Returns the alternate date format which is used to parse user input for searching dates in addition to the default format. |
| JSDataSet | getDataSet | Executes the search and returns the results as a JSDataSet |
| String | getDataSource | Returns the data source used by the search object |
| String | getDateFormat | Returns the date format which is used to parse user input for searching dates |
| JSFoundSet | getFoundSet | Creates a factory foundset, runs the search and returns it |
| QBSelect | getQuery | Creates and returns a query object parsed from the user input |
| SearchProvider | getSearchProvider | Gets a SearchProvider by specified name (alias) |
| String | getSearchText | Gets the raw, unparsed input text |
| Boolean | loadRecords | Loads records on the specified foundset. |
| SimpleSearch | removeAlternateDateFormat | Remove alternative date format which is used to parse user input for searching dates in addition to the default format. |
| SimpleSearch | setDateFormat | Sets the date formatting which will be used to parse user input |
| SimpleSearch | setSearchAllColumns | Sets that all columns are to be searchable |
| SimpleSearch | setSearchText | Set the raw, user input to be parsed |
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 |
|---|---|---|---|
| String | 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
simpleSearch.addAlternateDateFormat("dd/MM/yyyy");
simpleSearch.addAlternateDateFormat("MM-yyyy");
simpleSearch.addAlternateDateFormat("MM/yyyy");
simpleSearch.addAlternateDateFormat("MMM yyyy");
simpleSearch.addAlternateDateFormat("MMMM yyyy");
simpleSearch.addAlternateDateFormat("yyyy");
...
//The following are invalid formats
// simpleSearch.addAlternateDateFormat("dd/yyyy"); will throw an exception
// simpleSearch.addAlternateDateFormat("MM"); will throw an exception
Adds a search provider to the search object.
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| String | dataProviderID | The data provider that will be searched. Can be columns, related columns | Required |
| String | alias | The natural language name of the search provider. Used in explicit searches. | Optional. Default is same as data provider |
| Boolean | impliedSearch | Set this false to indicate that a provider is not searchable unless explicitly referenced | Optional. Default is True |
| Boolean | caseSensitive | Set this to be true to force case-sensitive search on this search provider | Optional. Default is False |
Returns SearchProvider
Get all search providers for this search object
Returns Array<SearchProvider>
Returns the alternate date format which is used to parse user input for searching dates in addition to the default format.
Returns Array<String>
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
Returns the data source used by the search object
Returns String
Returns the date format which is used to parse user input for searching dates
Returns String
Creates a factory foundset, runs the search and returns it
Returns JSFoundSet
Creates and returns a query object parsed from the user input
Returns QBSelect
Gets the specified SearchProvider
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| String | aliasOrDataProvider | The name or alias of the data provider | Required |
Returns SearchProvider or null if named SearchProvider is not found
Gets the raw, unparsed input text
Returns String
Loads records in the specified foundset
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| JSFoundSet | foundSet | The JSFoundSet object upon which to load records | Required |
Returns Boolean True indicates query was successful, although may have loaded zero records
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 |
|---|---|---|---|
| String | format | the alternate date format to be removed | Required |
Returns SimpleSearch
Sets the date formatting which will be used to parse user input
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| String | format | The format to use for date searches | Required |
Returns SimpleSearch Returns this SimpleSearch for convenience, method chaining
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
Set the raw, user input to be parsed
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| String | 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.
| Return Type | Method | Description |
|---|---|---|
| SearchProvider | addSubstitution | Add a substitution kev-value pair to this search provider |
| String | getAlias | Gets the alias of this search provider. |
| String | getDataProviderID | Gets the data provider ID |
| JSColumn | getJSColumn | Get the JSColumn object that corresponds to this search provider |
| JSTable | getJSTable | Get the JSTable object that corresponds to this search provider |
| String | getStringMatching | gets the String matching mode for this SearchProvider |
| Array<String> | getSubstitutionsKeys | Get all the keys for substitutions |
| String | getSubstitutionValue | Get the substitution value for a given key |
| Boolean | isCaseSensitive | Indicates if this SearchProvider is case-sensitive |
| Boolean | isCastInteger | Indicates if this SearchProvider will cast INTEGER to TEXT |
| Boolean | isImpliedSearch | Indicates if this SearchProvider is an implied search |
| SearchProvider | setAlias | Sets the natural language name for this SearchProvider |
| SearchProvider | setCaseSensitive | Specifies if this SearchProvider will perform case-sensitive searches |
| SearchProvider | setCastInteger | Specifies if this SearchProvider will cast INTEGER to TEXT |
| SearchProvider | setImpliedSearch | Specifies if this search provider is included in implied search |
| SearchProvider | setStringMatching | Sets the String matching mode for this SearchProvider |
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 |
|---|---|---|---|
| String | key | A string to be replaced | Required |
| String | value | The value to replace it with | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining
Gets the alias of this search provider.
Returns String The alias, or null if none was specified
Gets the data provider ID
Returns String The data provider which will be searched
Get the JSColumn object that corresponds to this search provider
Returns JSColumn
Get the JSTable object that corresponds to this search provider
Returns JSTable
Get the matching mode for this search provider.
Returns String
Get all the keys for substitutions
Get the substitution value for a given key
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| String | key | The substitution key | Required |
Returns String
Indicates if this SearchProvider is case-sensitive
Returns Boolean
Indicates if this SearchProvider will cast INTEGER values to TEXT in the query
Returns [Boolean]
Indicates if this SearchProvider is an implied search
Returns Boolean
Sets the natural language name for this SearchProvider
The alias can be used in explicit searches
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| String | alias | The alias | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining
Specifies if this SearchProvider will perform case-sensitive searches
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| Boolean | caseSensitive | The value for case-sensitive | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining
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
| Type | Name | Summary | Required |
|---|---|---|---|
| Boolean | castInteger | True if the INTEGER values should cast to TEXT | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining
Specifies if this search provider is included in implied search
A value of true indicates that the provider will always be searched
A value of false indicates that provider will ONLY be searched when used in explicit field matching
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| Boolean | impliedSearch | The value for implied search | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining
Sets the string matching mode for this SearchProvider
Params
| Type | Name | Summary | Required |
|---|---|---|---|
| String | stringMatching | The desired matching mode | Required |
Returns SearchProvider this SearchProvider for convenience, method chaining