8. Using Wildcards to Retrieve Data from GBDS¶

When retrieving data from GBDS through List Transactions and List People, it is possible to use wildcard operators to filter the results.

When performing a List Transactions using the qualityStatus parameter, the key, biographic, and label fields can be filtered with wildcard operators.

The available wildcard operators are described below:

8.1. List Transactions¶

8.1.1. Suffixes¶

The key or biographic field can contain an id:value or id|value, e.g. Name:John Doe, where four suffixes can be added.
- [anywhere]: This is the default suffix, if none is written, this is selected. In this case, the application will look for the id or value provided on any part of the string.
  
  Example: If the key is name[anywhere]:rob, it will search for names like “Robbin” and surname like “Robarts”.
- [atstart]: If this suffix is used, the application will look for the id or value provided at the beginning of the string.
  
  Example: If a key is passportNumber:123[atstart], it will search for the passport numbers that start with 123 and return all.
- [atend]: If this suffix is used, the application will look for the id or value provided at the end of the string.
  
  Example: If a key is passportNumber:123[atend], it will search for the passport numbers that end with 123. name[atend]:son will search for names and surnames that end with “son”.
- [exact]: If this suffix is used, the application will search for exact matches to the given search string.
  
  Example: If a key is passportNumber:123[exact], it will search for the passport numbers that are exactly equal to 123.

Warning

Those wildcards operators are SUFFIXES, so they must be inserted either AFTER the ID or AFTER the Value.

Note

Additionally, ID and Value can have different suffixes for each one, so it is possible to have operations such as name[exact]:rob[atstart], where it will search the field called exactly “Name” for values that start with “rob”.

8.1.2. Prefixes¶

The biographic field can also have a PREFIX. This prefix can only be used in the FIRST biographic, before the id. Other prefixes will be ignored. This prefix will define which logical operation the application will execute between ALL biographics and keys fields. The accepted values are [and] and [or], the first being the default value.

Example: If the biographic is [or]id:value, an OR operation will be performed in all keys and biographics, as: (Key1 OR Biographic1 OR Biographic2).

This prefix can be combined with a suffix, so values as [or]id:value[exact] are accepted.

8.2. List People¶

When performing a List People, the operator parameter can be either and or or. The selected operator will be applied in key, biographic, and label comparisons. After, an and comparison with the desired date value will be performed for filtering the data.

Example: If the operator is or, the comparison for filtering the data will be: ((Key1 OR Biographic1 OR Biographic2 OR Label1) AND Date).

8.2.1. Restrictions matchMode¶

Inside the restriction object, it is possible to select one out of five match modes when the restriction is a Biographic or a Key. The possible values and their operations are listed below.

Danger

Everything that is not a letter, a number or an underline is a separator. A separator between numbers or letters will cause tokenization of the complete word/number in all modes excluding EXACT and NOT_EQUALS.

Important

In the restriction filter value, only the blank space `` `` is a delimiter and will tokenize the words/numbers. This behavior do not occur in EXACT and NOT_EQUALS matchMode.

Warning

The search parameter is sensible to special characters in letters, as â, é, ñ, and others.

EXACT - The exact operation searches the entire value provided. Using exact will not tokenize the restricted expression. This mode is case sensitive.
- Example: The call should return the value “Jose Arruda”. Using EXACT with “Jose” or “Arruda” will work to return the desired value.
  
  Note
  
  Searches as “Jo” or “rrud” will not return Jose Arruda.
- Example 2: The call should return a numeric value from a document, like “123456”. Using EXACT the value MUST be “123456”.
  
  Note
  
  Searches with the value “123” or “456” will not return the correct value.
  
  Important
  
  If the value is stored with a separator, the separator must be in the restriction value.
START - The start operation will filter values tokenizing each word or number set divided by a separator.
- Example: If the user is restricting START for the “Jo” value, some possible returns could be:
```
Jose Arruda
John Doe
Marie Johnson
```
- Example 2: If the user is restricting START for the “Jose Arruda” value, some possible returns could be:
```
Jose Arruda
Jose Silva
Pedro Thomas Arruda
```
- Example 3: If the user is restricting START for the “123” value, some possible returns could be:
```
1234567
123.456
456-123
a-b 123
```
- Example 4: If the user is restricting START for the “123.456” value, some possible returns could be:
```
123.456
123.456.789-90
```
ANYWHERE - The anywhere operation will search for the value in any part of the word or number.
- Example: If the user restriction is ANYWHERE for the “Jo” value, some possible returns could be:
```
Jose Arruda
Major
Pejorative
Banjo
```
- Example 2: Searching for “12” could return:
```
123456
641256
114-4312
a-b 123
```
- Example 3: If the user restriction is ANYWHERE for the “Jo Ru” value, some possible returns could be:
```
Jose Arruda
Ruth Silva
Havier Russel
```
END - The end operation will search for the value at the END of the token. Like START, this operation will tokenize the words/numbers for each separator.
- Example: If the user restriction END for the “son” value, some possible returns could be:
```
Eric Johnson
Hudson Santos
```
- Example 2: If the user is restricting END for the “Jose Arruda” value, some possible returns could be:
```
Jose Arruda
Jose Silva
Pedro Thomas Arruda
Arruda Bastos
```
- Example 3: If the user is restricting END for the “123” value, some possible returns could be:
```
4567123
123.456
456-123
a-b 123
```
- Example 4: If the user is restricting END for the “123.456” value, some possible returns could be:
```
123.456
789.123.456
```
NOT_EQUALS - Not equals match mode works inverse as EXACT operation. It will filter and DISCARD exact matches to the provided value and show ALL OTHERS values. This mode is case sensitive.
- Example: Using NOT_EQUALS with the value “Jose” could return:
```
John Doe
Marie Johnson
Josemar Rodrigues
```
- Example 2: Using NOT_EQUALS with the value “123” could return:
```
4567123
123456
```