Functions

ObjectQuel includes built-in functions for inspecting data quality, testing existence, and transforming values inline within your queries. Type-checking functions let you guard against mixed-type fields, exists() produces efficient existence joins, and utility functions like ifnull() and concat() handle common value transformations.

explanation

Type and Value Checking Functions

These functions inspect the type or emptiness of a field value and return a boolean. They are used in where clauses to filter rows based on data quality or type, but can also appear in the retrieve clause.

is_empty()

Returns true if the value is null, an empty string, or 0. Useful for filtering out records with missing data:

// Find products with no description
$results = $entityManager->executeQuery("
    range of p is App\\Entity\\ProductEntity
    retrieve (p) where is_empty(p.description)
");

// Find products that do have a description
$results = $entityManager->executeQuery("
    range of p is App\\Entity\\ProductEntity
    retrieve (p) where not is_empty(p.description)
");

is_numeric()

Returns true if the value is an integer, a float, or a numeric string. Use this when a field may contain mixed content and you need to ensure the value is safe to use in arithmetic:

$results = $entityManager->executeQuery("
    range of r is App\\Entity\\ReadingEntity
    retrieve (r) where is_numeric(r.value)
");

is_integer()

Returns true only for values that are strictly an integer type, excluding floats and numeric strings:

$results = $entityManager->executeQuery("
    range of r is App\\Entity\\ReadingEntity
    retrieve (r) where is_integer(r.value)
");

is_float()

Returns true only for values that are strictly a float type, excluding integers and numeric strings:

$results = $entityManager->executeQuery("
    range of r is App\\Entity\\ReadingEntity
    retrieve (r) where is_float(r.value)
");
is_numeric() is broader than is_integer() or is_float(). A numeric string like "42" passes is_numeric() but fails both is_integer() and is_float(). Use is_integer() or is_float() when you need strict PHP type matching, and is_numeric() when a coercible value is sufficient.

Existence Check

exists()

Returns true if at least one related row exists for the given entity alias. The argument must be an entity alias, not a property reference:

// Find users who have at least one order
$results = $entityManager->executeQuery("
    range of u is App\\Entity\\UserEntity
    range of o is App\\Entity\\OrderEntity via u.orders
    retrieve (u) where exists(o)
");

// Find users who have no orders
$results = $entityManager->executeQuery("
    range of u is App\\Entity\\UserEntity
    range of o is App\\Entity\\OrderEntity via u.orders
    retrieve (u) where not exists(o)
");
exists() vs any(): exists() belongs in the where clause and filters which rows are returned — it produces an existence test without pulling related data into the result set. any() belongs in the retrieve clause and adds a 1/0 column to each result row indicating whether related rows exist.

Utility Functions

ifnull()

Returns the first argument if it is not null, otherwise returns the fallback value:

// Display a placeholder when a product has no description
$results = $entityManager->executeQuery("
    range of p is App\\Entity\\ProductEntity
    retrieve (p.name, ifnull(p.description, 'No description available'))
");

// Fall back to a secondary field
$results = $entityManager->executeQuery("
    range of u is App\\Entity\\UserEntity
    retrieve (u.name, ifnull(u.displayName, u.username))
");

concat()

Concatenates two or more expressions into a single string. Accepts any mix of field references, string literals, and parameters:

// Build a full name from separate fields
$results = $entityManager->executeQuery("
    range of u is App\\Entity\\UserEntity
    retrieve (concat(u.firstName, ' ', u.lastName))
");

// Combine fields and a literal prefix
$results = $entityManager->executeQuery("
    range of p is App\\Entity\\ProductEntity
    retrieve (p.id, concat('SKU-', p.sku, '-', p.variantCode))
");