Prerequisites

Before reading this section you should make yourself familiar with the Filters for Data Reading because filters are used as arguments in almost all search calls.

You may also want to take a quick look at type codes prior to reading the following sections.

Overview of Search Methods

In the Groovy API, the general purpose search methods are:

...

For the complete list of available methods, please refer to the most recent JavaDoc API.

Return Types

All methods, with the exception of count, always return a (possibly empty) collection of objects matching the passed-in filter criteria. The structure of each object depends on the structure of the underlying Java class.

Anchor
find find

Type Codes

The first parameter of the method api.find() is always a Type Code. This short code identifies the entity to search. The most common type codes you will encounter are the following ones: 

...

For searching in Price Parameters, you should almost exclusively use specialized methods api.findLookupTable and api.findLookupTableValues. For more details see Searching in Price Parameters.

Using Attribute Names in Searches

When working with attributes, instead of their database field names you can use technical names in api.find filters. In this case, column names are also returned as keys.

• The api.find/stream methods accept field names from the meta data (custom column names).
• The api.find/stream methods accept sort column names from the meta data.
• When field names are used and a raw DB result is returned, the resulting object has keys from the meta data.
• When loading a list of entities (a result of api.find/stream), the function List api.namedEntities(List) has to be called to convert the result of api.find to a list of maps that have keys from the meta data.
  If you use the api.find/stream without the List of fields, you get Objects representing the result which can be converted to a List of hashmaps with named fields using api.namedEntities() or iterator.nextNamedEntity().

Limitations of api.find()

There are several things you have to be aware of when using the search methods:

• The number of rows the method api.find can return is limited by a server parameter. It is configurable per partition and by default it is set to 200. You can retrieve the max rows by calling api.getMaxFindResultsLimit. Read how to overcome this limitation below.
   A warning is displayed if the number of returned rows returned equals 200 or formulaEngine.script.findMaxResults and the maxRows parameter of the find was not specified (=0). 
• When filtering the attributed fields (attribute1, ..., attribute30), you need to pass strings to filters because all attributed fields are stored in the database as strings. This is mainly an issue with Dates. Find out how to convert them properly.
• Because of the previous point, you cannot use sorting on numbers (integers, real) because api.find returns and sorts the data as strings. When sorting ($100, $70, $25) ascending, the result will be ($100, $25, $70).
• Using api.find/api.stream it is not possible to retrieve the typedId field. These methods produce a DB query and in the DB we store an "id" field. So, to get typedId you would have to manually concatenate the "id" and "type" fields with a dot in a postprocessing logic.

Sorting

If you need to sort the data by a specific column, use the method overload which allows you to specify the sortBy parameter. You can sort by several attributes, separated by commas.

...

api.find("Q", Filter.equal("uniqueName", "P-1457"))[0]

Loading More Than 200 Rows

There is a limit on how many rows the method api.find() can retrieve. It is configurable per partition and is by default set to 200 rows. You can retrieve the current settings by calling api.getMaxFindResultsLimit().

...

Searching in Product/Customer Extensions

There are two ways to search in Product (PX) or Customer (CX) Extensions. If you do not need advanced features like sorting, you should always use the method api.productExtension() or api.customerExtension().

...

api.find("PX", Filter.equal("name", "GLOBAL.ListPrices"), Filter.greaterOrEqual("attribute1", api.targetDate().format("yyyy-MM-dd"))) 

Searching in Price Parameters

Again, there are two ways to search in Price Parameters (PP). If you do not need advanced features, you should always use the method api.findLookupTableValues().

...

You can find the list of all type codes here.

Searching for Dates in Attributed Fields

If you use a date in your filter, there is one thing you need to be aware of when filtering attributed fields with Date or Timestamp type (i.e. attribute1, attribute2, ... attribute30). Since the values in attributed fields are stored as strings in the database, you need to convert your Date object into a proper String representation. The comparison in the database is then lexicographical but because it follows formatting standards it works well.

...