Oihana PHP Arango

CountQueryTrait uses trait:short, \oihana\models\traits\ConditionsTrait, trait:short, trait:short, trait:short, trait:short, trait:short

Provides an ArangoDB query to count the number of documents in a collection.

Supports both optimized (unfiltered) and filtered modes.

Tags
author

Marc Alcaraz (eKameleon)

since
1.0.0

Table of Contents

Constants

FACETS  : string = 'facets'
The 'facets' parameter constant.
FILTERS  : string = 'filters'
The 'filters' parameter constant.
SEARCHABLE  : string = 'searchable'
The 'searchable' parameter key.

Properties

$activable  : bool
$facets  : array<string|int, mixed>|null
The facet settings.
$filters  : array<string|int, mixed>|null
Defines all valid filtering conditions for queries used in the list() and count() methods.
$searchable  : array<string|int, mixed>|null
The searchable fields swept by the classic `?search=` `LIKE` (see {@see prepareSearch()}). A list of field names; an entry may instead be an array carrying its name under {@see Search::KEY} plus options such as {@see Search::REQUIRES} to gate the field by permission:
$searchOperator  : string
The default operator combining the words of a `?search=` term **within a field** during the classic `LIKE` sweep ({@see prepareSearch()}): {@see \oihana\arango\db\enums\Logic::AND} (every word must be found in the field, order-independent) or {@see \oihana\arango\db\enums\Logic::OR} (the whole term matched as one substring — the default, backward-compatible).
$searchSeparators  : string
The extra characters (beyond whitespace) that split a `?search=` term into words for the `AND` operator of the classic `LIKE` sweep ({@see prepareSearch()}).
$view  : array<string|int, mixed>|null
The model-level ArangoSearch declaration (`AQL::VIEW` block, see {@see Search}).

Methods

bind()  : string
Bind a value to an AQL query variable.
bindCollection()  : string
Bind a collection name to an AQL query variable.
bindView()  : string
Bind the model's declared View name (`AQL::VIEW` block, {@see Search::NAME}) to an AQL query variable — collection bind parameters (`@@view`) are valid for View names as well.
getViewLinks()  : array<string, ArangoSearchLink>
Returns the desired per-collection link map of the declared View — the model's collection linked with {@see buildViewLink()} — or an empty map when the model has no collection.
getViewName()  : string|null
Returns the name of the declared View ({@see Search::NAME} of the `AQL::VIEW` block), or `null` when the model declares none.
hasViewSearch()  : bool
Indicates whether the View search is active: the model declares a named View (`AQL::VIEW` block) with at least one searched field, **and** the request carries a non-empty search term.
initializeActivable()  : static
Initialize the activable flag to check if the documents are 'active' or not.
initializeFacets()  : static
Initialize the 'facets' property.
initializeFilters()  : static
Initialize the 'filters' property.
initializeSearchable()  : static
Initialize the 'searchable' property.
initializeSearchOperator()  : static
Initialize the `LIKE` sweep operator ({@see $searchOperator}) from the `Search::OPERATOR` init key. An explicit value is normalized to {@see Logic::AND} / {@see Logic::OR}; an absent key keeps the default ({@see Logic::OR}, backward-compatible).
initializeSearchSeparators()  : static
Initialize the `LIKE` sweep word separators ({@see $searchSeparators}) from the `Search::SEPARATORS` init key. Accepts a string of characters or a list of characters (joined to a string); an absent key keeps the default (the hyphen). Only meaningful with the `AND` operator. See {@see Search::SEPARATORS}.
initializeView()  : static
Initialize the model-level ArangoSearch declaration (`AQL::VIEW` block) and lazily provision the View, mirroring the collection provisioning of `initializeCollection()`: when the model is lazy and the declared View does not exist, it is created from the declaration — the searched fields (dotted paths supported) are linked on the model's collection with the declared {@see Search::ANALYZER}. An existing View is never altered — inspect and resynchronize explicitly with {@see viewDiff()} / {@see viewSync()} (or the `views` action of the `arangodb` command).
prepareActive()  : string|null
Prepare the 'active' variable.
prepareFilter()  : string|null
Prepare the AQL query filtering with specific definitions.
prepareSearch()  : string|null
Prepare the searchable AQL conditions — the classic `?search=` `LIKE` sweep, a parenthesized `OR` of case-insensitive `LIKE()` predicates over every (permitted) searchable field, used when no View search is active.
prepareViewSearch()  : string|null
Prepare the relevance-ranked `SEARCH` expression of an active View search, or `null` when the View search is inactive (no `AQL::VIEW` declaration, no searched fields, or no search term) — the caller then falls back to the classic `LIKE` sweep of {@see prepareSearch()}.
viewDiff()  : DiffReport
Compares the model's View declaration with the server state and reports the differences, without touching anything.
viewSync()  : DiffReport
Reconciles the model's View with its declaration: creates it when missing, repairs a drift with `updateProperties()` (the View stays available while the inverted index rebuilds in the background), and leaves {@see DiffStatus::IN_SYNC}, {@see DiffStatus::INVALID} or {@see DiffStatus::UNREACHABLE} reports untouched.
alterFilterKey()  : string
Apply the key-side (left) `alt` transformation to a key expression.
buildCountQuery()  : string
Build the AQL query used to count documents.
buildFilteredScope()  : array{0: string, 1: ?string}
Builds the `FOR` segment and the conjunctive `FILTER` clause shared by the list-family queries.
buildViewLink()  : ArangoSearchLink
Builds the View link of the model's collection from the `AQL::VIEW` declaration: every searched field (dotted paths become nested fields) is indexed with its resolved Analyzer — the per-field {@see Search::ANALYZER} when declared, otherwise the View-level one.
buildViewSearchGroups()  : array<string, array<string|int, string>>
Builds the per-Analyzer expression groups of the View search under the historical `OR` grammar : each comma-separated term is bound whole and matched in one shot per field (`doc.<field> IN TOKENS(@search_N, …)`, whose `IN` semantics already `OR` the term's tokens), plus the optional phrase and fuzzy branches. This is the exact grammar emitted when no field opts into {@see Search::OPERATOR} `AND` — see {@see prepareViewSearch()}.
buildViewSearchGroupsWithOperator()  : array<string, array<string|int, string>>
Builds the per-Analyzer expression groups when at least one field opts into {@see Search::OPERATOR} `AND`. Each comma-separated term is split into words (whitespace) ; a field then combines those words with its resolved operator :
getSearchableSpecs()  : array<string, array<string, mixed>>
Normalizes the model's `AQL::SEARCHABLE` list into a per-field specification map `field => [ (Search::REQUIRES => …)? ]`, the single source consumed by {@see prepareSearch()} (the `LIKE` sweep) and by the `searchable` fallback of {@see getViewFieldSpecs()}.
getViewFieldSpecs()  : array<string, array<string, mixed>>
Normalizes the searched fields of the `AQL::VIEW` declaration into a per-field specification map `field => [ Search::BOOST => float, … ]` — the single source of truth from which {@see getViewSearchFields()} derives the boost map and {@see prepareViewSearch()} resolves the per-field options.
getViewSearchFields()  : array<string, float>
Normalizes the searched fields into a `field => boost` map — a boost-only façade over {@see getViewFieldSpecs()}, used by {@see buildViewLink()} and {@see viewDiff()} which only care about the field paths and their weights.
ngramMatch()  : string
Builds the `NGRAM_MATCH(doc.<field>, @term [, threshold], "<analyzer>")` core of a {@see Search::NGRAM} branch (without the surrounding boost). The threshold is inlined only when the field declares one, else the server default applies. Shared by the whole-term and the per-word emissions.
prepareFacets()  : string|null
Prepare the query with AQL facets definitions.
prepareFilterBetween()  : string
Prepares an inclusive `between` (range) clause: `key >= @min && key <= @max`.
prepareFilterComparator()  : string
Prepares the filter clause with a specific operator.
prepareFilterKey()  : string
Prepares the filter clause with a specific key and document, with optional function transformations via 'alt' parameter.
prepareFilterValue()  : string
Prepare the filter clause with a specific value to evaluates.
pushWholeTermField()  : void
Pushes the whole-term match of one field onto the Analyzer groups — the base `doc.<field> IN TOKENS(@term, …)` (boosted when the field weight is not `1`), the optional exact-phrase bonus and the optional fuzzy branch, plus the {@see Search::NGRAM} branch when declared. This is the `OR`-grammar emission, shared by {@see buildViewSearchGroups()} (every field) and by the `OR` fields of {@see buildViewSearchGroupsWithOperator()}.
resolveFieldSearchSpec()  : array{0: string[], 1: float, 2: int, 3: bool, 4: string}
Resolves the per-field search facets shared by both group builders : the Analyzers indexing the field (a per-field {@see Search::ANALYZER} overrides the View-level one, a single Analyzer normalized to a one-element list), the boost, the fuzzy tolerance and phrase bonus (a per-field value overrides the View-level default), and the `doc.<field>` accessor (with the `[*]` array marker stripped — the flat path already matches any element of the indexed array, and the `SEARCH` grammar rejects the expansion form).
splitSearchTermWords()  : array<string|int, string>
Splits an `AND`-operator search term into its words, on whitespace plus the given extra separator characters ({@see Search::SEPARATORS}). Whitespace always splits; `$separators` adds literal characters (a string, or a list of characters joined to one), `null` falls back to the hyphen default, and an empty value splits on whitespace only. The extra characters are regex-escaped, so any punctuation is safe. Empty words are dropped.
collectMatchFields()  : array<int, string>
Collects the field names referenced by a `match` payload, for the permission gate. Mirrors the shape read by {@see \oihana\arango\db\helpers\buildCombinedInlineFilter()}: the explicit `all` / `any` / `none` lists expose their field under `key`, while the simple object form (`{ propertyID: …, value: … }`) uses its keys directly.

Constants

FACETS

The 'facets' parameter constant.

public string FACETS = 'facets'

FILTERS

The 'filters' parameter constant.

public string FILTERS = 'filters'

SEARCHABLE

The 'searchable' parameter key.

public string SEARCHABLE = 'searchable'

Properties

$facets

The facet settings.

public array<string|int, mixed>|null $facets = []

$filters

Defines all valid filtering conditions for queries used in the list() and count() methods.

public array<string|int, mixed>|null $filters = []

$searchable

The searchable fields swept by the classic `?search=` `LIKE` (see {@see prepareSearch()}). A list of field names; an entry may instead be an array carrying its name under {@see Search::KEY} plus options such as {@see Search::REQUIRES} to gate the field by permission:

public array<string|int, mixed>|null $searchable = [] 
AQL::SEARCHABLE =>
[
    'name' ,                                                       // public
    [ Search::KEY => 'salary' , Search::REQUIRES => 'hr:salary' ], // gated
]

$searchOperator

The default operator combining the words of a `?search=` term **within a field** during the classic `LIKE` sweep ({@see prepareSearch()}): {@see \oihana\arango\db\enums\Logic::AND} (every word must be found in the field, order-independent) or {@see \oihana\arango\db\enums\Logic::OR} (the whole term matched as one substring — the default, backward-compatible).

public string $searchOperator = \oihana\arango\db\enums\Logic::OR

Set once per model through the Search::OPERATOR init key. The View search carries its own operator inside the AQL::VIEW block (per field), see Search::OPERATOR.

$searchSeparators

The extra characters (beyond whitespace) that split a `?search=` term into words for the `AND` operator of the classic `LIKE` sweep ({@see prepareSearch()}).

public string $searchSeparators = \oihana\enums\Char::HYPHEN

A string of characters; set once per model through the Search::SEPARATORS init key (a list of characters is normalized to a string at init). The default is the hyphen (-) so « Jean-Marc » splits like « Jean Marc »; an empty string keeps hyphenated codes whole. Only used in AND mode. See Search::SEPARATORS.

$view

The model-level ArangoSearch declaration (`AQL::VIEW` block, see {@see Search}).

public array<string|int, mixed>|null $view = null

When present (with a Search::NAME), the ?search= parameter switches from the simple LIKE sweep to an index-accelerated, relevance-ranked SEARCH against the declared View.

Methods

bind()

Bind a value to an AQL query variable.

public bind(mixed $value[, array<string|int, mixed> &$binds = [] ][, string|null $to = null ]) : string
Parameters
$value : mixed

The value to bind to the query.

$binds : array<string|int, mixed> = []

Reference to the array of existing bind variables.

$to : string|null = null

Optional name of the bind variable. If null, a unique name is generated.

Tags
throws
BindException

If the provided bind variable name is invalid.

Return values
string —

The formatted bind variable (including the "@" prefix as needed) for use in the query.

bindCollection()

Bind a collection name to an AQL query variable.

public bindCollection([array<string|int, mixed> &$binds = [] ][, array<string|int, mixed> $init = [] ]) : string

Prepares a bind variable for a collection name. Uses the collection defined in $init or falls back to $this->collection if none is provided.

Parameters
$binds : array<string|int, mixed> = []

Reference to the array of existing bind variables. If null, a new array is used.

$init : array<string|int, mixed> = []

Optional initialization array with keys:

  • Arango::COLLECTION => the collection name to bind
  • Arango::NAME => optional bind variable name
Tags
throws
BindException

If the bind variable name is invalid.

Return values
string —

The formatted bind variable representing the collection.

bindView()

Bind the model's declared View name (`AQL::VIEW` block, {@see Search::NAME}) to an AQL query variable — collection bind parameters (`@@view`) are valid for View names as well.

public bindView([array<string|int, mixed> &$binds = [] ]) : string
Parameters
$binds : array<string|int, mixed> = []

Reference to the array of existing bind variables.

Tags
throws
BindException

If the bind variable name is invalid.

Return values
string —

The formatted bind variable representing the View.

getViewLinks()

Returns the desired per-collection link map of the declared View — the model's collection linked with {@see buildViewLink()} — or an empty map when the model has no collection.

public getViewLinks() : array<string, ArangoSearchLink>
Tags
throws
ValidationException
Return values
array<string, ArangoSearchLink>

getViewName()

Returns the name of the declared View ({@see Search::NAME} of the `AQL::VIEW` block), or `null` when the model declares none.

public getViewName() : string|null
Return values
string|null

hasViewSearch()

Indicates whether the View search is active: the model declares a named View (`AQL::VIEW` block) with at least one searched field, **and** the request carries a non-empty search term.

public hasViewSearch([array<string|int, mixed>|string|null $search = [] ]) : bool
Parameters
$search : array<string|int, mixed>|string|null = []

The $init array (reads Arango::SEARCH) or the search term itself.

Tags
throws
ValidationException
Return values
bool

initializeActivable()

Initialize the activable flag to check if the documents are 'active' or not.

public initializeActivable([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeFacets()

Initialize the 'facets' property.

public initializeFacets([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeFilters()

Initialize the 'filters' property.

public initializeFilters([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeSearchable()

Initialize the 'searchable' property.

public initializeSearchable([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeSearchOperator()

Initialize the `LIKE` sweep operator ({@see $searchOperator}) from the `Search::OPERATOR` init key. An explicit value is normalized to {@see Logic::AND} / {@see Logic::OR}; an absent key keeps the default ({@see Logic::OR}, backward-compatible).

public initializeSearchOperator([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeSearchSeparators()

Initialize the `LIKE` sweep word separators ({@see $searchSeparators}) from the `Search::SEPARATORS` init key. Accepts a string of characters or a list of characters (joined to a string); an absent key keeps the default (the hyphen). Only meaningful with the `AND` operator. See {@see Search::SEPARATORS}.

public initializeSearchSeparators([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeView()

Initialize the model-level ArangoSearch declaration (`AQL::VIEW` block) and lazily provision the View, mirroring the collection provisioning of `initializeCollection()`: when the model is lazy and the declared View does not exist, it is created from the declaration — the searched fields (dotted paths supported) are linked on the model's collection with the declared {@see Search::ANALYZER}. An existing View is never altered — inspect and resynchronize explicitly with {@see viewDiff()} / {@see viewSync()} (or the `views` action of the `arangodb` command).

public initializeView([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface
ValidationException
Return values
static

prepareActive()

Prepare the 'active' variable.

public prepareActive([array<string|int, mixed> $init = [] ][, array<string|int, mixed>|null &$binds = null ][, string $docRef = AQL::DOC ]) : string|null
Parameters
$init : array<string|int, mixed> = []
$binds : array<string|int, mixed>|null = null
$docRef : string = AQL::DOC
Tags
throws
BindException
Return values
string|null

prepareFilter()

Prepare the AQL query filtering with specific definitions.

public prepareFilter([array<string|int, mixed>|null $init = [] ][, array<string|int, mixed>|null &$binds = null ][, string $docRef = AQL::DOC ][, array<string|int, mixed> $auth = [] ]) : string|null
Parameters
$init : array<string|int, mixed>|null = []
$binds : array<string|int, mixed>|null = null
$docRef : string = AQL::DOC
$auth : array<string|int, mixed> = []
Tags
throws
BindException
ConstantException
ContainerExceptionInterface
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
ValidationException
Return values
string|null

prepareSearch()

Prepare the searchable AQL conditions — the classic `?search=` `LIKE` sweep, a parenthesized `OR` of case-insensitive `LIKE()` predicates over every (permitted) searchable field, used when no View search is active.

public prepareSearch([array<string|int, mixed>|string|null $search = [] ][, array<string|int, mixed>|null &$binds = null ][, array<string|int, mixed>|null $searchable = null ][, string $docRef = AQL::DOC ]) : string|null

The comma-separated terms and the fields are always OR-ed. How the words of a single term combine within a field follows the model's $searchOperator (Search::OPERATOR init key):

  • Logic::OR (default) matches the whole term as one substring (LIKE(doc.name, "%marc fourcade%")), so it needs the words adjacent and in order — the historical, byte-for-byte grammar;
  • Logic::AND splits the term on whitespace and requires every word in the same field (( LIKE(doc.name, "%marc%") && LIKE(doc.name, "%fourcade%") )), order-independent.
Parameters
$search : array<string|int, mixed>|string|null = []
$binds : array<string|int, mixed>|null = null
$searchable : array<string|int, mixed>|null = null
$docRef : string = AQL::DOC
Tags
throws
BindException
example 
?search=Marc,Marco
Return values
string|null

prepareViewSearch()

Prepare the relevance-ranked `SEARCH` expression of an active View search, or `null` when the View search is inactive (no `AQL::VIEW` declaration, no searched fields, or no search term) — the caller then falls back to the classic `LIKE` sweep of {@see prepareSearch()}.

public prepareViewSearch([array<string|int, mixed>|string|null $search = [] ][, array<string|int, mixed>|null &$binds = null ][, string $docRef = AQL::DOC ]) : string|null

The grammar keeps the ?search= contract (comma-separated terms, OR everywhere, values bound — never inlined). Per term and per field:

  • the base match doc.<field> IN TOKENS(@search_N, "<analyzer>") (both sides analyzed), weighted by BOOST(…, <boost>) when the field boost differs from 1; a field reaching into an array of objects has its [*] expansion marker stripped here (doc.contactPoints.email IN …, not doc.contactPoints[*].email): the SEARCH grammar rejects array expansion, and the flat path already matches any element of the indexed array — see buildViewLink();
  • with a per-field or View-level Search::PHRASE, an exact-phrase bonus BOOST(PHRASE(doc.<field>, @search_N), <boost × 2>); a field may override the View-level flag (an explicit false opts that field out);
  • with a per-field or View-level Search::FUZZY > 0, a typo-tolerant LEVENSHTEIN_MATCH(doc.<field>, @search_N, <fuzzy>); a field may override the View-level tolerance — an explicit 0 opts that field out while the rest stays fuzzy.

Field expressions are grouped by their resolved Analyzer (a field may override the View-level Search::ANALYZER) and each group is wrapped in its own ANALYZER(…, "<analyzer>"), the groups being OR-ed together. With a single Analyzer the output is a single ANALYZER(…) wrap, byte for byte the classic form.

Search::REQUIRES gates the search by the request authorizer (Arango::AUTHORIZER, see isAuthorized()) at two levels: on the AQL::VIEW block it gates the whole search, inside a field entry it gates that field; the two combine with AND (fail-open without an authorizer). If the View-level gate is denied, or permissions remove every field, the expression is false — the search matches nothing and never falls back to searching everything.

When the request carries an active language (Arango::LANG, the ?lang= parameter), localized fields (those declaring Search::LANG) join the SEARCH only when their locale matches; locale-agnostic fields always do. An active language matching no field is ignored — the SEARCH is never emptied (within the permitted set).

Parameters
$search : array<string|int, mixed>|string|null = []

The $init array (reads Arango::SEARCH) or the search term itself.

$binds : array<string|int, mixed>|null = null

Bind variables, populated by reference.

$docRef : string = AQL::DOC

The document variable the fields hang off.

Tags
throws
BindException
ValidationException
Return values
string|null —

The SEARCH expression, or null when the View search is inactive.

viewDiff()

Compares the model's View declaration with the server state and reports the differences, without touching anything.

public viewDiff() : DiffReport

On top of the field/analyzer drift detected by ViewManagementTrait::viewDiff(), the model-level report validates the coherence of the declaration itself: a missing Search::NAME, no searched field, no collection, an analyzer or a collection unknown to the server all resolve to DiffStatus::INVALID — such a View is never created nor synchronized automatically.

Tags
throws
ValidationException
Return values
DiffReport

viewSync()

Reconciles the model's View with its declaration: creates it when missing, repairs a drift with `updateProperties()` (the View stays available while the inverted index rebuilds in the background), and leaves {@see DiffStatus::IN_SYNC}, {@see DiffStatus::INVALID} or {@see DiffStatus::UNREACHABLE} reports untouched.

public viewSync() : DiffReport
Tags
throws
ValidationException
Return values
DiffReport —

The viewDiff() report, with $applied set when the View has been created or updated.

alterFilterKey()

Apply the key-side (left) `alt` transformation to a key expression.

protected alterFilterKey(string $key[, array<string|int, mixed> $init = [] ]) : string

Thin wrapper over static::alterExpression(): it resolves the alt parameter into its key/value sides via static::resolveAltSides() and applies the key-side chain. The three legacy alt forms (string, list of functions, function-with-params) keep transforming the key only, unchanged.

Parameters
$key : string

The key expression to transform.

$init : array<string|int, mixed> = []

Filter initialization array containing the 'alt' parameter.

Tags
throws
UnsupportedOperationException
ValidationException
Return values
string —

The transformed key expression.

buildCountQuery()

Build the AQL query used to count documents.

protected buildCountQuery([array<string|int, mixed> $init = [] ][, array<string|int, mixed> &$bindVars = [] ]) : string

The query can be optimized (unfiltered) or fully filtered depending on $init. Example AQL output:

RETURN LENGTH(
  FOR doc IN @@collection
    FILTER doc.active == true && ...
    RETURN 1
)
Parameters
$init : array<string|int, mixed> = []

Initialization parameters.

$bindVars : array<string|int, mixed> = []

Reference to bind variables.

Tags
throws
BindException
ConstantException
ContainerExceptionInterface
NotFoundExceptionInterface
ReflectionException
DependencyException
NotFoundException
UnsupportedOperationException
ValidationException
Return values
string —

The compiled AQL query string.

buildFilteredScope()

Builds the `FOR` segment and the conjunctive `FILTER` clause shared by the list-family queries.

protected buildFilteredScope([array<string|int, mixed> $init = [] ][, array<string|int, mixed> &$bindVars = [] ]) : array{0: string, 1: ?string}
Parameters
$init : array<string|int, mixed> = []

The query options.

$bindVars : array<string|int, mixed> = []

The bind variables, populated by reference.

Tags
throws
BindException
ConstantException
ContainerExceptionInterface
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
ValidationException
Return values
array{0: string, 1: ?string} —

The [ $for, $filter ] pair.

buildViewLink()

Builds the View link of the model's collection from the `AQL::VIEW` declaration: every searched field (dotted paths become nested fields) is indexed with its resolved Analyzer — the per-field {@see Search::ANALYZER} when declared, otherwise the View-level one.

protected buildViewLink() : ArangoSearchLink

A field may reach a sub-field of an array of objects with the [*] expansion marker (e.g. contactPoints[*].email). The marker is stripped here (stripArrayExpansion()) so the link declares the flat nested path (contactPoints → email): ArangoSearch (Community) descends into the array on its own — no Enterprise nested flag is needed for this (non-correlated) search. The matching query strips the marker too — the SEARCH grammar rejects array expansion, see prepareViewSearch(). The stripped path is validated (assertAttributeName()) to reject a malformed declaration early.

A field whose resolved Analyzer equals the link-level default is emitted as an empty node (no analyzers key) rather than spelling the default out: the server normalizes a field whose analyzers equal the link default to } (the redundant mention is dropped), so spelling it out would make the declared form differ forever from the stored one and viewDiff() would report a permanent false drift. The link carries no link-level analyzers, so its default is the server default (identity) — computed here rather than hard-coded so the elimination stays correct if a link-level analyzer is introduced later.

Tags
throws
ValidationException
Return values
ArangoSearchLink

buildViewSearchGroups()

Builds the per-Analyzer expression groups of the View search under the historical `OR` grammar : each comma-separated term is bound whole and matched in one shot per field (`doc.<field> IN TOKENS(@search_N, …)`, whose `IN` semantics already `OR` the term's tokens), plus the optional phrase and fuzzy branches. This is the exact grammar emitted when no field opts into {@see Search::OPERATOR} `AND` — see {@see prepareViewSearch()}.

protected buildViewSearchGroups(string $search, array<string|int, mixed>|null &$binds, string $docRef, array<string|int, mixed> $fields, string $modelAnalyzer, bool $globalPhrase, int $globalFuzzy) : array<string, array<string|int, string>>
Parameters
$search : string

The raw ?search= term string (comma-separated).

$binds : array<string|int, mixed>|null

Bind variables, populated by reference.

$docRef : string

The document variable the fields hang off.

$fields : array<string|int, mixed>

The resolved, gated per-field specs.

$modelAnalyzer : string

The View-level Analyzer (a per-field override is respected).

$globalPhrase : bool

The View-level phrase-bonus default.

$globalFuzzy : int

The View-level Levenshtein tolerance default.

Tags
throws
BindException
Return values
array<string, array<string|int, string>> —

Analyzer name => list of expressions, in first-seen order.

buildViewSearchGroupsWithOperator()

Builds the per-Analyzer expression groups when at least one field opts into {@see Search::OPERATOR} `AND`. Each comma-separated term is split into words (whitespace) ; a field then combines those words with its resolved operator :

protected buildViewSearchGroupsWithOperator(string $search, array<string|int, mixed>|null &$binds, string $docRef, array<string|int, mixed> $fields, string $modelAnalyzer, bool $globalPhrase, int $globalFuzzy, string $globalOperator[, string|array<string|int, mixed>|null $separators = null ]) : array<string, array<string|int, string>>
  • OR (default) reproduces the whole-term match (pushWholeTermField()), so a mixed View keeps its loose fields loose ;
  • AND requires every word in the same field (( doc.<field> IN TOKENS(@w0, …) && doc.<field> IN TOKENS(@w1, …) )), the fuzzy branch (when enabled) widening each word (( … IN TOKENS(@w, …) || LEVENSHTEIN_MATCH(…, @w, …) )), and the phrase bonus (when enabled) kept on the whole term as a ranking boost OR-ed on top — an adjacency match implies the words, so the matched set is unchanged.

The whole-term bind is materialized only when a field needs it (an OR field, or an AND field carrying the phrase bonus), never left dangling. Groups are OR-ed between fields and between terms by prepareViewSearch().

Parameters
$search : string

The raw ?search= term string (comma-separated).

$binds : array<string|int, mixed>|null

Bind variables, populated by reference.

$docRef : string

The document variable the fields hang off.

$fields : array<string|int, mixed>

The resolved, gated per-field specs.

$modelAnalyzer : string

The View-level Analyzer (a per-field override is respected).

$globalPhrase : bool

The View-level phrase-bonus default.

$globalFuzzy : int

The View-level Levenshtein tolerance default.

$globalOperator : string

The View-level operator default (Logic::AND / Logic::OR).

$separators : string|array<string|int, mixed>|null = null

The extra AND word separators (Search::SEPARATORS); null = the hyphen default.

Tags
throws
BindException
Return values
array<string, array<string|int, string>> —

Analyzer name => list of expressions, in first-seen order.

getSearchableSpecs()

Normalizes the model's `AQL::SEARCHABLE` list into a per-field specification map `field => [ (Search::REQUIRES => …)? ]`, the single source consumed by {@see prepareSearch()} (the `LIKE` sweep) and by the `searchable` fallback of {@see getViewFieldSpecs()}.

protected getSearchableSpecs([array<string|int, mixed>|null $searchable = null ]) : array<string, array<string, mixed>>

Each entry of the list is either:

  • a plain field name (string) → a public field, no options;
  • an array carrying the field name under Search::KEY plus its options (e.g. Search::REQUIRES) → keeps the list homogeneous (no mixed numeric/string keys). The map form field => [ … ] is also tolerated (the field falls back to the entry key).
Parameters
$searchable : array<string|int, mixed>|null = null

An explicit list overriding the model's searchable property.

Return values
array<string, array<string, mixed>>

getViewFieldSpecs()

Normalizes the searched fields of the `AQL::VIEW` declaration into a per-field specification map `field => [ Search::BOOST => float, … ]` — the single source of truth from which {@see getViewSearchFields()} derives the boost map and {@see prepareViewSearch()} resolves the per-field options.

protected getViewFieldSpecs() : array<string, array<string, mixed>>

Search::FIELDS entries accept a numeric boost shorthand or an array carrying Search::BOOST, Search::FUZZY, Search::ANALYZER, Search::LANG, Search::PHRASE and Search::REQUIRES; when the declaration has no fields, the model's searchable list is used with a neutral boost. A per-field option is kept in the spec only when it is explicitly declared — an absent key means "inherit the View-level default", which prepareViewSearch() resolves so that an explicit value (0 included) overrides the global tolerance.

Tags
throws
ValidationException
Return values
array<string, array<string, mixed>>

getViewSearchFields()

Normalizes the searched fields into a `field => boost` map — a boost-only façade over {@see getViewFieldSpecs()}, used by {@see buildViewLink()} and {@see viewDiff()} which only care about the field paths and their weights.

protected getViewSearchFields() : array<string, float>
Tags
throws
ValidationException
Return values
array<string, float>

ngramMatch()

Builds the `NGRAM_MATCH(doc.<field>, @term [, threshold], "<analyzer>")` core of a {@see Search::NGRAM} branch (without the surrounding boost). The threshold is inlined only when the field declares one, else the server default applies. Shared by the whole-term and the per-word emissions.

protected ngramMatch(array<string|int, mixed> $spec, string $path, string $term) : string
Parameters
$spec : array<string|int, mixed>

The field spec (must carry a Search::NGRAM entry).

$path : string

The doc.<field> accessor.

$term : string

The bound term (@search_N or @search_N_M).

Return values
string —

The NGRAM_MATCH(…) expression.

prepareFacets()

Prepare the query with AQL facets definitions.

protected prepareFacets(array<string|int, mixed>|null $init[, array<string|int, mixed>|null &$binds = null ][, string $docRef = AQL::DOC ][, string $logicalOperator = Logic::AND ]) : string|null
Parameters
$init : array<string|int, mixed>|null
$binds : array<string|int, mixed>|null = null
$docRef : string = AQL::DOC
$logicalOperator : string = Logic::AND
Return values
string|null

prepareFilterBetween()

Prepares an inclusive `between` (range) clause: `key >= @min && key <= @max`.

protected prepareFilterBetween(array<string|int, mixed> $init, array<string|int, mixed>|null &$binds, string $docRef, callable $resolve, bool $defaultBounds) : string

The compared key is alt-aware (it flows through static::alterFilterKey()). Each bound is resolved by $resolve, which differs per filter type — a raw bind for numbers/strings, the date machinery (now / timezone) for dates.

Bound omission is type-driven:

  • $defaultBounds = false (number/string): an omitted bound drops its side, yielding a one-sided range (key >= @min or key <= @max).
  • $defaultBounds = true (date): an omitted bound still emits a clause; the resolver maps the null value to "now", so the range is always two-sided.
Parameters
$init : array<string|int, mixed>

The filter init (reads min / max).

$binds : array<string|int, mixed>|null

The bind variables, populated by reference.

$docRef : string

The document reference.

$resolve : callable

fn(mixed $value, ?array &$binds): string — resolves a bound to AQL.

$defaultBounds : bool

Whether an omitted bound still emits a clause (dates) or is dropped.

Tags
throws
UnsupportedOperationException
ValidationException
Return values
string

prepareFilterComparator()

Prepares the filter clause with a specific operator.

protected prepareFilterComparator([array<string|int, mixed> $init = [] ]) : string
Parameters
$init : array<string|int, mixed> = []
Return values
string

prepareFilterKey()

Prepares the filter clause with a specific key and document, with optional function transformations via 'alt' parameter.

protected prepareFilterKey([string|array<string|int, mixed>|null $init = [] ][, string $docRef = AQL::DOC ]) : string

Supports function chaining:

  • Single function: "alt":"lower"
  • Multiple functions: "alt":["trim","lower"]
  • Functions with params: "alt":[["trim",1],"lower"]
Parameters
$init : string|array<string|int, mixed>|null = []

Filter initialization array

$docRef : string = AQL::DOC

Document reference (default: AQL::DOC)

Tags
throws
UnsupportedOperationException
ValidationException
example 
// Simple key
prepareFilterKey(['key' => 'name'], 'doc')
// Returns: "doc.name"

// With single function
prepareFilterKey(['key' => 'name', 'alt' => 'lower'], 'doc')
// Returns: "LOWER(doc.name)"

// With function chain
prepareFilterKey(['key' => 'name', 'alt' => ['trim', 'lower']], 'doc')
// Returns: "LOWER(TRIM(doc.name))"

// With parameters
prepareFilterKey(['key' => 'code', 'alt' => [['substring', 0, 3]]], 'doc')
// Returns: "SUBSTRING(doc.code, 0, 3)"
Return values
string —

The transformed key expression

prepareFilterValue()

Prepare the filter clause with a specific value to evaluates.

protected prepareFilterValue([array<string|int, mixed>|null $init = [] ][, array<string|int, mixed>|null &$binds = null ]) : string

Binds the raw value, then applies the value-side (right) alt chain when one is set (object form alt:{ key:.. , val:.. } or val:true mirror):

  • scalar value → the chain wraps the bind placeholder, e.g. LOWER(@value).
  • array value (e.g. op:in) → the chain is mapped over each element via an inline projection, e.g. @value[* RETURN LOWER(CURRENT)]. The single bind still holds the whole array, so existing binding behavior is preserved.
Parameters
$init : array<string|int, mixed>|null = []
$binds : array<string|int, mixed>|null = null
Tags
throws
BindException
UnsupportedOperationException
ValidationException
Return values
string

pushWholeTermField()

Pushes the whole-term match of one field onto the Analyzer groups — the base `doc.<field> IN TOKENS(@term, …)` (boosted when the field weight is not `1`), the optional exact-phrase bonus and the optional fuzzy branch, plus the {@see Search::NGRAM} branch when declared. This is the `OR`-grammar emission, shared by {@see buildViewSearchGroups()} (every field) and by the `OR` fields of {@see buildViewSearchGroupsWithOperator()}.

protected pushWholeTermField(array<string|int, mixed> &$groups, array<string|int, mixed> $spec, string $path, string $term, array<string|int, mixed> $analyzers, float $weight, bool $phrase, int $fuzzy) : void
Parameters
$groups : array<string|int, mixed>

Analyzer name => list of expressions, mutated by reference.

$spec : array<string|int, mixed>

The resolved field spec.

$path : string

The doc.<field> accessor.

$term : string

The bound whole term (@search_N).

$analyzers : array<string|int, mixed>

The Analyzers indexing the field (IN TOKENS side).

$weight : float

The field boost.

$phrase : bool

Whether to add the exact-phrase bonus.

$fuzzy : int

The Levenshtein tolerance (0 disables the branch).

resolveFieldSearchSpec()

Resolves the per-field search facets shared by both group builders : the Analyzers indexing the field (a per-field {@see Search::ANALYZER} overrides the View-level one, a single Analyzer normalized to a one-element list), the boost, the fuzzy tolerance and phrase bonus (a per-field value overrides the View-level default), and the `doc.<field>` accessor (with the `[*]` array marker stripped — the flat path already matches any element of the indexed array, and the `SEARCH` grammar rejects the expansion form).

protected resolveFieldSearchSpec(array<string|int, mixed> $spec, int|string $field, string $modelAnalyzer, bool $globalPhrase, int $globalFuzzy, string $docRef) : array{0: string[], 1: float, 2: int, 3: bool, 4: string}
Parameters
$spec : array<string|int, mixed>

The resolved field spec.

$field : int|string

The field key (the dotted path, [*] allowed).

$modelAnalyzer : string

The View-level Analyzer.

$globalPhrase : bool

The View-level phrase-bonus default.

$globalFuzzy : int

The View-level Levenshtein tolerance default.

$docRef : string

The document variable the field hangs off.

Return values
array{0: string[], 1: float, 2: int, 3: bool, 4: string} —

[ analyzers, weight, fuzzy, phrase, path ].

splitSearchTermWords()

Splits an `AND`-operator search term into its words, on whitespace plus the given extra separator characters ({@see Search::SEPARATORS}). Whitespace always splits; `$separators` adds literal characters (a string, or a list of characters joined to one), `null` falls back to the hyphen default, and an empty value splits on whitespace only. The extra characters are regex-escaped, so any punctuation is safe. Empty words are dropped.

protected splitSearchTermWords(string $term[, string|array<string|int, mixed>|null $separators = null ]) : array<string|int, string>
Parameters
$term : string

The raw comma-term (may hold several words).

$separators : string|array<string|int, mixed>|null = null

The extra separator characters (string / list / null=default hyphen).

Return values
array<string|int, string> —

The non-empty words, in order.

collectMatchFields()

Collects the field names referenced by a `match` payload, for the permission gate. Mirrors the shape read by {@see \oihana\arango\db\helpers\buildCombinedInlineFilter()}: the explicit `all` / `any` / `none` lists expose their field under `key`, while the simple object form (`{ propertyID: …, value: … }`) uses its keys directly.

private collectMatchFields(array<string|int, mixed> $match) : array<int, string>
Parameters
$match : array<string|int, mixed>

The match payload (already validated as an array by the caller).

Return values
array<int, string> —

The referenced sub-field names (possibly empty).

On this page

Search results