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

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)

OperatorNameSummary

-

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

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

TypeNameSummaryRequired

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 TypeMethodDescription

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

TypeNameSummaryRequired

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

TypeNameSummaryRequired

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

TypeNameSummaryRequired

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

TypeNameSummaryRequired

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

TypeNameSummaryRequired

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

TypeNameSummaryRequired

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

TypeNameSummaryRequired

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

TypeNameSummaryRequired

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 TypeMethodDescription

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

TypeNameSummaryRequired

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

Returns Array<String>

getSubstitutionValue

Get the substitution value for a given key

Params

TypeNameSummaryRequired

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

TypeNameSummaryRequired

alias

The alias

Required

Returns SearchProvider this SearchProvider for convenience, method chaining

setCaseSensitive

Specifies if this SearchProvider will perform case-sensitive searches

Params

TypeNameSummaryRequired

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