Skip to content

Home

Jump to bottom
Paolo edited this page Sep 27, 2023 · 25 revisions

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

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.

Quoted Strings

Use double quotes to escape tokenization

Example

"John Smith" // matches only "John Smith" and not "Smithers Johnson", "John Doe" at "Smithefield Road", etc

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

last-name:smith // matches "John Smith", but not John Doe at "Smithefield Road", etc.

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

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

Case Sensitivity

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

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"

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

//	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);

svySearch

A single scope that contains the classes

Method Summary

createSimpleSearch

Params

Type Name Summary Required
Number dataSource The data source used Required

returns

SimpleSearch

example

scopes.svySearch.createSimpleSearch(foundset);
scopes.svySearch.createSimpleSearch(record);
scopes.svySearch.createSimpleSearch('db:/example_data/orders');

SimpleSearch

A class which models a search on a particular data source and its supporting class

Method Summary

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

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

addSearchProvider

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

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
String 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
JSFoundSet foundSet The JSFoundSet object upon which to load records 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
String 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
String 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
String searchText The raw text to be parsed Required

Returns SimpleSearch Returns this SimpleSearch for convenience, method chaining

SearchProvider

A class which models the component of the search that maps to a single data provider.

Method Summary

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

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

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

Returns Array<String>

getSubstitutionValue

Get the substitution value for a given key

Params

Type Name Summary Required
String 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
String 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
Boolean 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

Type Name Summary Required
Boolean castInteger True if the INTEGER values should cast to TEXT Required

Returns SearchProvider this SearchProvider for convenience, method chaining

setImpliedSearch

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

setStringMatching

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

Clone this wiki locally