⭐️ If you like MikroORM, give it a star on GitHub and consider sponsoring its development! ⭐️
This is documentation for an unreleased version. For the latest API, see version 6.4.
Version: Next
raw
Callable
raw<T, R>(sql, params): R
Creates raw SQL query fragment that can be assigned to a property or part of a filter. This fragment is represented
by RawQueryFragment class instance that can be serialized to a string, so it can be used both as an object value
and key. When serialized, the fragment key gets cached and only such cached key will be recognized by the ORM.
This adds a runtime safety to the raw query fragments.
raw() helper is required since v6 to use a raw fragment in your query, both through EntityManager and QueryBuilder.
// as a value await em.find(User,{ time:raw('now()')}); // as a key await em.find(User,{[raw('lower(name)')]: name.toLowerCase()}); // value can be empty array await em.find(User,{[raw('(select 1 = 1)')]:[]});
The raw helper supports several signatures, you can pass in a callback that receives the current property alias:
The raw helper can be used within indexes and uniques to write database-agnostic SQL expressions. In that case, you can use '??' to tag your database identifiers (table name, column names, index name, ...) inside your expression, and pass those identifiers as a second parameter to the raw helper. Internally, those will automatically be quoted according to the database in use:
// On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("country") // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`country`) @Index({ name:'custom_idx_on_name',expression:(table, columns)=>raw(`create index ?? on ?? (??)`,['custom_idx_on_name', table, columns.name])}) @Entity({ schema:'library'}) exportclassAuthor{...}
You can also use the quote tag function to write database-agnostic SQL expressions. The end-result is the same as using the raw function regarding database identifiers quoting, only to have a more elegant expression syntax:
@Index({ name:'custom_idx_on_name',expression:(table, columns)=> quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})`}) @Entity({ schema:'library'}) exportclassAuthor{...}
Creates raw SQL query fragment that can be assigned to a property or part of a filter. This fragment is represented by
RawQueryFragment
class instance that can be serialized to a string, so it can be used both as an object value and key. When serialized, the fragment key gets cached and only such cached key will be recognized by the ORM. This adds a runtime safety to the raw query fragments.The
raw
helper supports several signatures, you can pass in a callback that receives the current property alias:You can also use the
sql
tagged template function, which works the same, but supports only the simple string signature:When using inside filters, you might have to use a callback signature to create new raw instance for every filter usage.
The
raw
helper can be used within indexes and uniques to write database-agnostic SQL expressions. In that case, you can use'??'
to tag your database identifiers (table name, column names, index name, ...) inside your expression, and pass those identifiers as a second parameter to theraw
helper. Internally, those will automatically be quoted according to the database in use:You can also use the
quote
tag function to write database-agnostic SQL expressions. The end-result is the same as using theraw
function regarding database identifiers quoting, only to have a more elegant expression syntax: