xlucene-translator / index
index
Classes
| Class | Description |
|---|---|
| BaseSQLDialect | The SQL that every supported engine writes the same way. |
| DuckDBDialect | The DuckDB dialect. |
| PostgresDialect | The PostgreSQL dialect, using PostGIS for geo queries. |
Interfaces
| Interface | Description |
|---|---|
| SQLQueryParts | The parts of a SQL statement, before they are joined. |
| SQLSortInput | A sort term whose direction is optional, for code that calls a frame's orderBy. |
Variables
NOTHING_READABLE
constNOTHING_READABLE:"NULL"="NULL"
Defined in: sql-builder/dist/src/dialects/base.d.ts:8
The projection used when no field may be returned.
Elasticsearch still returns and counts the hits, just with an empty _source, so the SQL
needs a valid projection that carries no data rather than an error or no rows.
Functions
buildSQLStatement()
buildSQLStatement(
parts,params,dialect):string
Defined in: sql-builder/dist/src/statement.d.ts:28
Build a complete, executable SQL statement from its parts.
This is the SQL counterpart of restrictSearchQuery. Callers should use it rather than
joining the parts themselves, since leaving out select would return restricted columns.
Parameters
| Parameter | Type |
|---|---|
parts | SQLQueryParts |
params | SQLSearchParams |
dialect | SQLDialect |
Returns
string
canRenderValueAs()
canRenderValueAs(
value,fieldType?):boolean
Defined in: sql-builder/dist/src/field-types.d.ts:19
Whether a value can be a value of this field type.
Used when a query names no field or a field pattern. A query that names its field was
already checked by the parser, but ba*:hello can expand to an integer column, where
"num" = 'hello' is a cast error that fails the whole query. Fields that return false
are left out of the expansion; in Elasticsearch they could not match either.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
fieldType? | xLuceneFieldType |
Returns
boolean
defaultNullOrder()
defaultNullOrder(
direction):SQLNullOrder
Defined in: sql-builder/dist/src/clauses.d.ts:31
Where nulls go when the sort does not say.
This follows DataFrame, which treats null as the smallest value: nulls come first when
ascending and last when descending. No engine's default matches:
| ascending | descending | |
|---|---|---|
Elasticsearch (missing defaults to _last) | last | last |
DuckDB (default_null_order) | last | last |
| PostgreSQL (a null is the largest value) | last | first |
DataFrame - what this returns | first | last |
So orderByTerms writes NULLS FIRST or NULLS LAST on every term. To get
Elasticsearch's behavior, pass nulls: 'last' on the sort.
Parameters
| Parameter | Type |
|---|---|
direction | "DESC" | "ASC" |
Returns
SQLNullOrder
getAvailableSQLDialects()
getAvailableSQLDialects():
string[]
Defined in: sql-builder/dist/src/dialects/index.d.ts:6
The names of the supported SQL dialects.
Returns
string[]
getSQLDialect()
getSQLDialect(
input?):SQLDialect
Defined in: sql-builder/dist/src/dialects/index.d.ts:13
Resolve the dialect option to a dialect, defaulting to DuckDB.
A dialect object is returned unchanged, so callers can pass their own subclass without registering it.
Parameters
| Parameter | Type |
|---|---|
input? | SQLDialect | SQLDialectName |
Returns
SQLDialect
groupByClause()
groupByClause(
groupBy?):string
Defined in: sql-builder/dist/src/clauses.d.ts:42
A complete GROUP BY clause, or ''.
Each entry is raw SQL, like an ORDER BY expression, so date_trunc('day', ts) is a
valid grouping key.
Parameters
| Parameter | Type |
|---|---|
groupBy? | readonly string[] |
Returns
string
inferFieldType()
inferFieldType(
value):xLuceneFieldType
Defined in: sql-builder/dist/src/field-types.d.ts:10
Infer a field type from a value's JavaScript type, for nodes that have no field_type.
The parser expands some:$array into terms that carry only a value, so the value's type
is all there is to go on.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
xLuceneFieldType
isMatchAllWildcard()
isMatchAllWildcard(
value):boolean
Defined in: sql-builder/dist/src/patterns.d.ts:12
Whether a wildcard value matches any value, so no pattern match is needed.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
boolean
isNumericFieldType()
isNumericFieldType(
fieldType?):boolean
Defined in: sql-builder/dist/src/field-types.d.ts:2
Parameters
| Parameter | Type |
|---|---|
fieldType? | xLuceneFieldType |
Returns
boolean
isTextFieldType()
isTextFieldType(
fieldType?):boolean
Defined in: sql-builder/dist/src/field-types.d.ts:3
Parameters
| Parameter | Type |
|---|---|
fieldType? | xLuceneFieldType |
Returns
boolean
orderByClause()
orderByClause(
sort?):string
Defined in: sql-builder/dist/src/clauses.d.ts:35
A complete ORDER BY clause, or '' when the query asked for no ordering.
Parameters
| Parameter | Type |
|---|---|
sort? | readonly SQLSort[] |
Returns
string
orderByTerms()
orderByTerms(
sort?):string
Defined in: sql-builder/dist/src/clauses.d.ts:33
The comma-separated ORDER BY terms, without the keyword, or '' for no ordering.
Parameters
| Parameter | Type |
|---|---|
sort? | readonly SQLSort[] |
Returns
string
parens()
parens(
expression):string
Defined in: sql-builder/dist/src/quoting.d.ts:37
Wrap an expression in parentheses so operator precedence cannot change its meaning.
An expression that is already one parenthesized group is left alone, to keep the generated SQL readable.
Parameters
| Parameter | Type |
|---|---|
expression | string |
Returns
string
quoteBoolean()
quoteBoolean(
value):string
Defined in: sql-builder/dist/src/quoting.d.ts:50
A boolean literal.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
string
quoteIdentifier()
quoteIdentifier(
name):string
Defined in: sql-builder/dist/src/quoting.d.ts:18
Quote an identifier, always.
Quoting every identifier means reserved words such as group, order and end work as
field names without a reserved-word list.
Case handling differs: DuckDB matches quoted identifiers case-insensitively, while PostgreSQL treats them as case-sensitive. A dialect that needs a normalized name should normalize it before calling this.
@terascope/data-types has its own copy so that it does not depend on a query builder.
Parameters
| Parameter | Type |
|---|---|
name | string |
Returns
string
quoteLiteral()
quoteLiteral(
value):string
Defined in: sql-builder/dist/src/quoting.d.ts:30
Quote a value as a SQL string literal.
Doubling single quotes is the only escaping needed. DuckDB and PostgreSQL (with
standard_conforming_strings on, the default since 9.1) treat a backslash in a
single-quoted string as an ordinary character. An engine that does not can override
SQLDialect.stringLiteral.
Do not use core-utils' jsStringEscape here: it escapes for JavaScript, so it would
change C:\path and would not escape the single quote.
Parameters
| Parameter | Type |
|---|---|
value | string |
Returns
string
quoteNumber()
quoteNumber(
value):string
Defined in: sql-builder/dist/src/quoting.d.ts:41
A number literal. Throws for NaN and Infinity, which have no correct SQL equivalent.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
string
sortDirection()
sortDirection(
value):"DESC"|"ASC"
Defined in: sql-builder/dist/src/clauses.d.ts:14
Validate a sort direction and return ASC or DESC.
The value comes from the request and is written into the statement as a keyword, so it is checked at runtime to prevent SQL injection.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
"DESC" | "ASC"
toEpochMillisText()
toEpochMillisText(
value):string
Defined in: sql-builder/dist/src/quoting.d.ts:64
A date as epoch milliseconds, for comparing with the ms member of a DuckDB date column
(STRUCT(ms BIGINT, tz_offset SMALLINT)). Any offset in the value is applied:
'2020-01-01T00:00:00+02:00' is 1577829600000.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
string
toLiteralString()
toLiteralString(
value):string
Defined in: sql-builder/dist/src/quoting.d.ts:66
A value as the text a SQL literal needs, or a thrown error for something that is not.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
string
toSQLSort()
toSQLSort(
sort):SQLSort
Defined in: sql-builder/dist/src/clauses.d.ts:56
A frame's sort term as a complete SQLSort, defaulting the direction to ascending.
Parameters
| Parameter | Type |
|---|---|
sort | SQLSortInput |
Returns
SQLSort
toUTCTimestampText()
toUTCTimestampText(
value):string
Defined in: sql-builder/dist/src/quoting.d.ts:58
A date as UTC text, ready to cast to a TIMESTAMP without a time zone.
DuckDB's TIMESTAMP cast drops a time zone offset instead of applying it:
CAST('2020-01-01T00:00:00+02:00' AS TIMESTAMP) is 2020-01-01 00:00:00. Converting to
UTC first gives the same instant in every engine and server time zone.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
string
wholeNumber()
wholeNumber(
value,name):number
Defined in: sql-builder/dist/src/quoting.d.ts:48
Validate a row count as a non-negative integer.
A LIMIT cannot be a bound parameter, so the number is written into the statement and is
checked to prevent SQL injection.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
name | string |
Returns
number
wildcardToLikePattern()
wildcardToLikePattern(
value):string
Defined in: sql-builder/dist/src/patterns.d.ts:10
Convert an xLucene wildcard value to a LIKE pattern.
* and ? become % and _. A literal %, _ or \ in the value is escaped, so the
generated SQL always includes ESCAPE '\'. Otherwise bar:100% would match 100anything.
Parameters
| Parameter | Type |
|---|---|
value | string |
Returns
string
References
CachedQueryAccess
Re-exports CachedQueryAccess
CachedTranslator
Re-exports CachedTranslator
getProjectablePaths
Re-exports getProjectablePaths
getReadableFields
Re-exports getReadableFields
QueryAccess
Re-exports QueryAccess
QueryAccessConfig
Re-exports QueryAccessConfig
restrictionCovers
Re-exports restrictionCovers
RestrictOptions
Re-exports RestrictOptions
RestrictSearchQueryOptions
Re-exports RestrictSearchQueryOptions
RestrictSQLQueryOptions
Re-exports RestrictSQLQueryOptions
translateSQLQuery
Re-exports translateSQLQuery
Translator
Re-exports Translator
TranslatorOptions
Re-exports TranslatorOptions
UtilsTranslateSQLOptions
Re-exports UtilsTranslateSQLOptions