String filtering
There are several filtering constraints designed to work especially with string attributes. They are useful for looking for entities with attributes that contain a specific string.
In the context of the limitations described in this chapter, you might be interested in the general rules for handling
data types and arrays described in the query language basics.
Attribute contains
- argument:string!
- the name of the entity attribute whose value will be scanned for the occurrence of the string in the second argument
- argument:string!
the arbitrary value to search for in the attribute value (case-sensitive)
The attributeContains searches the filterable or unique entity attribute
for the occurrence of the string. The constraint behaves exactly like the .
It's case-sensitive, works with national characters (since we're working with UTF-8 strings), and requires an exact
match of the searched string anywhere in the attribute value.
Returns a few products having a string epix in the attribute code.
Performance on large collections
An ordinary index is sorted by whole values, which tells evitaDB nothing about what appears in the middle of them.
This constraint is therefore answered by going through every distinct value of the attribute and testing each one.
That is fast enough for a few thousand distinct values, but it becomes the slowest part of the query once there are
hundreds of thousands.
If that is your situation, the attribute can be given a
SUBSTRING_SEARCH filter accelerator - an extra index that finds the matching
values directly instead of testing them all. It never changes which entities the query returns, only how fast they
are found, and searches for patterns shorter than three characters fall back to the ordinary behaviour.
The catch worth knowing before you plan around it: the accelerator costs memory, and it must be declared on the
attribute before the first entity is inserted - it cannot be switched on for a collection that already holds data.
It is also skipped for queries issued from inside a read-write session, which are always scanned - see
filter accelerators.
Attribute starts with
- argument:string!
- the name of the entity attribute whose value will be tested to see if it starts with the string in the second argument
- argument:string!
the arbitrary value to search for in the attribute value (case-sensitive)
The attributeStartsWith searches the filterable or unique entity attribute
and checks if it starts with the specified string. The constraint behaves exactly like the .
It's case-sensitive, works with national characters (since we're working with UTF-8 strings), and requires an exact
match of the search string at the beginning of the attribute value.
Returns a few pages of products that start with a garmin string in the code attribute.
Unlike attributeContains and attributeEndsWith, this constraint is
already fast on large collections and needs no
filter accelerator. Values are kept in sorted order, so everything starting
with the same prefix sits next to everything else that does: evitaDB jumps straight to the first such value and reads
forward until the prefix stops matching, without touching the rest of the attribute. This is why the
SUBSTRING_SEARCH accelerator deliberately does not cover attributeStartsWith - it could only make it slower.
Attribute ends with
- argument:string!
- the name of the entity attribute whose value will be tested to see if it ends with the string in the second argument
- argument:string!
the arbitrary value to search for in the attribute value (case-sensitive)
The attributeEndsWith searches the filterable or unique entity attribute
and checks if it ends with the specified string. The constraint behaves exactly like the
.
It's case-sensitive, works with national characters (since we're working with UTF-8 strings), and requires an exact
match of the search string at the end of the attribute value.
Returns a few products that end with a solar string in the code attribute.
Performance on large collections
An ordinary index is sorted by whole values, which tells evitaDB nothing about what appears in the middle of them.
This constraint is therefore answered by going through every distinct value of the attribute and testing each one.
That is fast enough for a few thousand distinct values, but it becomes the slowest part of the query once there are
hundreds of thousands.
If that is your situation, the attribute can be given a
SUBSTRING_SEARCH filter accelerator - an extra index that finds the matching
values directly instead of testing them all. It never changes which entities the query returns, only how fast they
are found, and searches for patterns shorter than three characters fall back to the ordinary behaviour.
The catch worth knowing before you plan around it: the accelerator costs memory, and it must be declared on the
attribute before the first entity is inserted - it cannot be switched on for a collection that already holds data.
It is also skipped for queries issued from inside a read-write session, which are always scanned - see
filter accelerators.