# Search

Search is key to any useful inventory or successful platform.

Stelace Search API leverages your Assets with dynamic matchmaking relying on typo-tolerant text search including Custom Attributes, Availability, Transaction states and geo-coordinates.

All it takes is an API call and a few dozens of milliseconds:

await stelace.search.list({
  query: 'Deloran' // did you notice the typo?
})

curl https://api.stelace.com/search \
  -u seck_test_rylx3ebUg0bNs1HkJKlqNHkI: \
  -d query=Deloran

A lot of things happen in parallel behind the scenes. Here are the most important ones:

Stelace only considers Assets that are available right now by default.
Full-text search relies on built-in name and description Asset properties. It’s very easy to add your own Custom Attributes to your Assets. Full-text search query relies on all your text Custom Attributes by default, in addition to built-in name and description.
Search is typo-tolerant so that “Delorean” cars will be returned as expected despite the missing “e”.
Default sorting applies if no order is specified: most recent Assets first. Search can meet your ranking needs with advanced yet elegant sorting options.

TIP

Note: with Stelace you don’t have to re-index your Assets to update sorting order. Sorting happens on the fly, for higher flexibility.

What makes Stelace search powerful is its dynamic nature, relying on availability concept. Each Asset can have several states in the future described by Availabilities.

# Availability and future states

Stelace Search can return Assets available in the future:

during a given period by specifying startDate and endDate,
with a given quantity available now or over a given period,
around some location.

# Date

If you specify startDate and endDate and don’t disable automatic Availability filtering availabilityFilter: { enabled: false }, only Assets available during the full period will show up in results.

If only startDate is specified, only Assets having some availability past this date will be returned.

# Quantity

If quantity is specified with dates, appropriate number of units have to be available over the related period. Quantity is 1 by default.

Please note that quantity may not be considered depending on the Asset Type infiniteStock property.

# Location

Locations can be passed as a geo-coordinate object, used as origin for calculations:

{
  …,
  location: {
    latitude: 34.046713,
    longitude: -118.107380
  },
  maxDistance: 100000
}

You can specify maxDistance in meters to exclude Assets too far from origin, set to 150000 by default.

# Filtering

Search filter offers a powerful syntax to combine Custom Attributes of any type and built-in attributes with boolean logic.

Here is how we can find all cars having either GPS or air conditioning and of make Ford, unless they are cheaper than $5000.

await stelace.search.list({
  filter: 'options[GPS, AC] > 1 AND (make == ford OR NOT (_price >= 5000))'
})

# Built-ins

Stelace default attributes of Asset objects must be preceded by an underscore as in “_price” to avoid confusion with your own Custom Attributes.

# Operators

# Boolean operators

From highest to lowest precedence:

NOT, that must be followed by an expression in parentheses,
AND / &&
OR / ||

You can use parentheses to ensure appropriate boolean precedence in your filter expression.

Custom Attributes of type boolean are very easy to use in filter. Let’s imagine one of your Assets has a boolean automaticTransmission Custom Attribute set to true. It will be returned by the following Search request, even if it is not available:

await stelace.search.list({
  filter: '_available OR automaticTransmission',
  availabilityFilter: { enabled: false }
})

Note that we use _available boolean built-in by disabling availabilityFilter, so that all Assets are included in Search results, not just available Assets (default behavior).

# Comparison operators

Number comparison operators <, <=, >=, >
Equality operator ==

Equality operator == can be used with Custom Attributes of type text as well, provided they’re shorter than 255 characters.

# List operator

Square brackets [] allow to enclose comma-separated values that must be wrapped in quotes when having special characters.

[] list must be preceded by a Custom Attribute name, of type tags or select.

attr[some, values]-like expression returns an integer corresponding to the number of matched values. It is either 0 or 1 for attributes of type select, but can be as high as the number of submitted values for tags type, meaning an Asset has them all.

You can use Number comparison operators to make your Search very precise and only return Assets having some number of matches. If you omit comparison when using attr[…] list expression, filter will include all Assets having at least one match in […] values.

# Sorting

You can sort your results by price and Custom Attributes of type number, boolean or text (max. 256 chars) in one or several steps. Each additional sort step acts as a tiebreaker.

You just have to provide a sort object in your API call:

{
  …
  sort: [
    { "_price": "asc" }, // built-ins denoted by trailing _ (underscore)
    { "seatingCapacity": "desc" }
  ]
}

# Sort by availability

You may need to get both available and unavailable Assets in Search results to implement some custom filtering on your side, e.g. in your UI.

To do so you can set availabilityFilter.enabled to false so that a built-in boolean attribute available will be added to each Asset. None will be excluded from Search results.

Let’s imagine you want to get available Assets first and then order by a popularity Custom Attribute:

await stelace.search.list({
  sort: [
    { _available: 'desc' },
    { popularity: 'desc' }
  ],
  availabilityFilter: {
    enabled: false
  }
})

# Similar assets or “More like this”

You can use similarTo array of Asset ids or single Asset id to search for similar Assets and still use any other Search parameter.

It can be a convenient way to build a “more like this” feature for your Users, depending on their browsing history in your inventory.

← Assets Availability →