@narrative.io/data-collaboration-sdk-ts 0.0.122 → 0.0.124

package/build/nql/NQLParser.js

@@ -93,7 +93,7 @@ function parseFieldFromString(fieldStr) {
         },
         field: f
             .map((field) => {
-            return field.replace('"value"', "value").replace('"type"', "type");
+            return field.replace("`value`", "value").replace("`type`", "type");
         })
             .join("."),
     };

package/build/nql/NqlBuilder.d.ts

@@ -0,0 +1,8 @@
+import { type NqlBudget } from "./Ast";
+import { type Select, type Expression, type Raw, type Table } from "./AstParser";
+type CompiledNql = string;
+export declare function compileSelect(q: Select): CompiledNql;
+export declare function compileBudget(budget: NqlBudget): CompiledNql;
+export declare function compileFrom(tables: Table[] | Raw): CompiledNql;
+export declare function compileExpression(n: Expression): CompiledNql;
+export {};

package/build/nql/NqlBuilder.js

@@ -0,0 +1,297 @@
+const quoteChar = '"';
+export function compileSelect(q) {
+    const columns = q.columns.map((e) => compileExpression(e));
+    const select = `SELECT ${columns.join(", ")}`;
+    const budget = q.budget !== null ? compileBudget(q.budget) : "";
+    const from = `FROM ${compileFrom(q.from)}`;
+    const where = q.where !== null ? `WHERE ${compileExpression(q.where)}` : "";
+    return `${select} ${from} ${where} ${budget}`;
+}
+export function compileBudget(budget) {
+    let period;
+    switch (budget.period.type) {
+        case "calendar_daily": {
+            period = "PER CALENDAR DAY";
+            break;
+        }
+        case "calendar_monthly": {
+            period = "PER CALENDAR MONTH";
+            break;
+        }
+        default:
+            unreachable(budget.period.type);
+    }
+    // eslint-disable-next-line prettier/prettier
+    return `LIMIT ${budget.amount.value} ${budget.amount.currency.toUpperCase()} ${period}`;
+}
+export function compileFrom(tables) {
+    if (isArray(tables)) {
+        return compileTableRefs(tables);
+    }
+    else {
+        return compileRawRef(tables.nql, tables.as);
+    }
+}
+function compileTableRefs(tables) {
+    function ref(table) {
+        switch (table.type) {
+            case "dataset":
+                return aliased(`company_data.${quote(table.datasetId.toString())}`, table.as, false);
+            case "rosetta_stone":
+                return aliased(`narrative.rosetta_stone`, table.as, false);
+            case "raw_table":
+                return aliased(table.nql, table.as, false);
+        }
+    }
+    function compileTableRef(table) {
+        let stmt = "";
+        // NB: by convention the first table in list will never have a join associated with it,
+        // hence the leading ' ' below does what we want.
+        if (table.join !== undefined) {
+            switch (table.join.joinType) {
+                case "comma": {
+                    stmt += ",";
+                    break;
+                }
+                case "cross": {
+                    stmt += " CROSS JOIN";
+                    break;
+                }
+                case "full": {
+                    stmt += " FULL OUTER JOIN";
+                    break;
+                }
+                case "inner": {
+                    stmt += " JOIN";
+                    break;
+                }
+                case "left": {
+                    stmt += " LEFT OUTER JOIN";
+                    break;
+                }
+                case "left_semi": {
+                    stmt += " LEFT SEMI JOIN";
+                    break;
+                }
+                case "right": {
+                    stmt += " RIGHT OUTER JOIN";
+                    break;
+                }
+                default:
+                    unreachable(table.join.joinType);
+            }
+            stmt += ` ${ref(table)}`;
+        }
+        else {
+            stmt += ref(table);
+        }
+        if (
+        // Prefer explicit `join !== undefined` to the use of the  `?` operator so that typescript
+        // compile knows that the join is defined in the subsequent lexical scope.
+        // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+        table.join !== undefined &&
+            table.join.condition !== null &&
+            table.join.conditionType !== "none") {
+            switch (table.join.conditionType) {
+                case "on": {
+                    stmt += " ON";
+                    break;
+                }
+                case "using": {
+                    stmt += " USING";
+                    break;
+                }
+                default:
+                    unreachable(table.join.conditionType);
+            }
+            stmt += ` ${compileExpression(table.join.condition)}`;
+        }
+        return stmt;
+    }
+    let nql = "";
+    for (const table of tables) {
+        const stmt = compileTableRef(table);
+        nql += stmt;
+    }
+    return nql;
+}
+export function compileExpression(n) {
+    switch (n.type) {
+        case "=":
+            return compileBinaryOperator("=", [n.left, n.right], n.as);
+        case "<>":
+            return compileBinaryOperator("<>", [n.left, n.right], n.as);
+        case "<":
+            return compileBinaryOperator("<", [n.left, n.right], n.as);
+        case "<=":
+            return compileBinaryOperator("<=", [n.left, n.right], n.as);
+        case ">":
+            return compileBinaryOperator("<=", [n.left, n.right], n.as);
+        case ">=":
+            return compileBinaryOperator("<=", [n.left, n.right], n.as);
+        case "+":
+            return compileBinaryOperator("+", n.operands, n.as);
+        case "/":
+            return compileBinaryOperator("/", n.operands, n.as);
+        case "*":
+            return compileBinaryOperator("*", n.operands, n.as);
+        case "-":
+            return compileBinaryOperator("-", n.operands, n.as);
+        case "||":
+            return compileBinaryOperator("||", n.operands, n.as);
+        case "and":
+            return compileBinaryOperator("AND", n.operands, n.as);
+        case "attribute_ref":
+            return compileAttributeRef(n.column, n.as);
+        case "between":
+            return compileBetween(n.operand, n.lower, n.upper, n.as);
+        case "dataset_column_ref":
+            return compileDatasetColumnRef(n.datasetId, n.column, n.as);
+        case "function":
+            return compileFunctionCall(n.name, n.args, n.as);
+        case "in":
+            return compileIn(n.expression, n.values, n.negated, n.as);
+        case "is_null":
+            return compileIsNull(n.operand, n.negated, n.as);
+        case "like":
+            return compileLike(n.value, n.pattern, n.negated, n.as);
+        case "lit":
+            return compileLit(n.value, n.value_type, n.as);
+        case "not":
+            return compileNot(n.operand, n.as);
+        case "or":
+            return compileBinaryOperator("OR", n.operands, n.as);
+        case "nql":
+            return raw(n);
+        case "raw_ref":
+            return compileRawRef(n.nql, n.as);
+        case "unary_-":
+            return compileUnaryMinus(n.operand, n.as);
+    }
+    return unreachable(n);
+}
+function compileAttributeRef(column, as) {
+    return aliased(`narrative.rosetta_stone.${quote(column)}`, as);
+}
+function compileBetween(operand, lower, upper, as) {
+    const operandNql = compileExpression(operand);
+    const lowerNql = compileExpression(lower);
+    const upperNql = compileExpression(upper);
+    return aliased(`${operandNql} BETWEEN ASYMMETRIC ${lowerNql} AND ${upperNql}`, as);
+}
+function compileBinaryOperator(op, operands, as) {
+    return aliased(`(${operands.map((e) => compileExpression(e)).join(` ${op} `)})`, as);
+}
+function compileDatasetColumnRef(datasetId, column, as) {
+    return aliased(`company_data.${quote(datasetId.toString())}.${quote(column)}`, as);
+}
+function compileFunctionCall(name, args, as) {
+    // Calling convenions for functions are all over the place:
+    //   - CAST is invoked as CAST($value AS $type)
+    //   - EXTRACT is invoked as EXTRACT($part FROM $value)
+    //   - etc., etc., with many exceptions
+    // We'll likely wanto types for all the functions we know how to support, or have every function
+    // described by the API, including providing a template for its calling convention. For now the
+    // below will get us a to a v1.
+    // Useful reference: https://calcite.apache.org/docs/reference.html#arithmetic-operators-and-functions
+    const argsNql = args.map((e) => compileExpression(e));
+    let callNql;
+    switch (name) {
+        case "CAST":
+            callNql = `CAST(${argsNql[0]} AS ${argsNql[1]})`;
+            break;
+        case "EXTRACT":
+            callNql = `EXTRACT(${argsNql[0]} FROM ${argsNql[1]})`;
+            break;
+        case "TRIM":
+            callNql = `TRIM(${argsNql[0]} ${argsNql[1]} FROM ${argsNql[2]})`;
+            break;
+        default: {
+            // hope for the best. definitely does not work in all cases.
+            callNql =
+                argsNql.length > 0 ? `${name}(${argsNql.join(", ")})` : `${name}`;
+        }
+    }
+    return aliased(callNql, as);
+}
+function compileIn(expression, values, negated, as) {
+    const op = !negated ? "IN" : "NOT IN";
+    const compiledValues = isArray(values)
+        ? `(${values.map((e) => compileExpression(e)).join(", ")})`
+        : raw(values);
+    return aliased(`${compileExpression(expression)} ${op} ${compiledValues}`, as);
+}
+function compileIsNull(operand, negated, as) {
+    const op = !negated ? "IS NULL" : "IS NOT NULL";
+    return compilePostfixUnaryOperator(op, operand, as);
+}
+function compileLike(value, pattern, negated, as) {
+    const op = !negated ? "LIKE" : "NOT LIKE";
+    return aliased(`${compileExpression(value)} ${op} ${str(pattern)}`, as);
+}
+function compileLit(value, valueType, as) {
+    let valueNql;
+    if (value !== null) {
+        switch (valueType.type) {
+            case "bool":
+                valueNql = str(value.toUpperCase());
+                break;
+            case "interval": {
+                if (valueType.period.includes("_")) {
+                    // split e.g. "year_month" into [YEAR, MONTH]
+                    const parts = valueType.period.split("_").map((s) => s.toUpperCase());
+                    valueNql = `INTERVAL ${str(value)} ${parts[0]} TO ${parts[1]}`;
+                }
+                else {
+                    valueNql = `INTERVAL ${str(value)} ${valueType.period.toUpperCase()}`;
+                }
+                break;
+            }
+            default:
+                // todo(mbabic) don't really know what to do here/how complicated this needs to be
+                valueNql = str(value);
+        }
+    }
+    else {
+        valueNql = "NULL";
+    }
+    return aliased(valueNql, as);
+}
+function compileNot(operand, as) {
+    return aliased(`NOT ${compileExpression(operand)}`, as);
+}
+function compilePostfixUnaryOperator(op, operand, as) {
+    return aliased(`(${compileExpression(operand)}) ${op}`, as);
+}
+function compileRawRef(nql, as) {
+    return aliased(nql, as);
+}
+function compileUnaryMinus(operand, as) {
+    return aliased(`-(${compileExpression(operand)})`, as);
+}
+function aliased(nql, as, parens) {
+    const alias = as !== undefined ? `${nql} AS ${quote(as)}` : nql;
+    if ((parens === undefined || parens) && as !== undefined) {
+        return `(${alias})`;
+    }
+    else {
+        return alias;
+    }
+}
+function str(s) {
+    // todo(mbabic) is this the right escaping for calcite?
+    return `'${s.replaceAll("'", "''")}'`;
+}
+function quote(s) {
+    return `${quoteChar}${s.replace(quoteChar, `\\${quoteChar}`)}${quoteChar}`;
+}
+function raw(n) {
+    return aliased(n.nql, n.as);
+}
+function isArray(ns) {
+    return Array.isArray(ns);
+}
+// typescript trick to help with checking exhaustivity of swith statements
+function unreachable(x) {
+    throw new Error("unreachable");
+}

package/build/nql/index.d.ts

@@ -1,5 +1,6 @@
 import { BaseApi } from "../base-api";
 import type { Plan } from "./SubstraitParser";
+import { type NqlAst } from "./Ast";
 import type { Nql, NqlField, NqlResult, NqlCompileResult, NqlQueryInput, NqlExpression, NqlWhere, NqlFilterBinaryExpression, NqlBooleanExpression, NqlFilterExpression, NqlFilterUnaryExpression } from "./types";
 /**
  * A class for accessing the NQL API.
@@ -27,6 +28,14 @@ declare class NqlApi extends BaseApi {
      * @returns {Promise<NqlCompileResult>} A promise that resolves with the result of the NQL compilation.
      */
     parseNql(nqlQuery: NqlQueryInput): Promise<Plan>;
+    /**
+     * Validates an NQL query and returns an abstract syntax tree (AST) representing a structured form of
+     * the query.
+     *
+     * @param {string} nqlQuery - The NQL query to validate.
+     * @returns {Promise<NqlCompileResult>} A promise that resolves with the result of the NQL validation.
+     */
+    validateNql(nqlQuery: NqlQueryInput): Promise<NqlAst>;
     /**
      * Gets an existing NQL query by it's id
      *
@@ -35,4 +44,4 @@ declare class NqlApi extends BaseApi {
      */
     getNqlByJobId(id: string): Promise<NqlResult>;
 }
-export { NqlApi, type Nql, type NqlField, type NqlResult, type NqlQueryInput, type NqlCompileResult, type NqlExpression, type NqlWhere, type NqlFilterExpression, type NqlBooleanExpression, type NqlFilterBinaryExpression, type NqlFilterUnaryExpression, };
+export { NqlApi, type Nql, type NqlAst, type NqlField, type NqlResult, type NqlQueryInput, type NqlCompileResult, type NqlExpression, type NqlWhere, type NqlFilterExpression, type NqlBooleanExpression, type NqlFilterBinaryExpression, type NqlFilterUnaryExpression, };

package/build/nql/index.js

@@ -42,6 +42,17 @@ class NqlApi extends BaseApi {
         const response = await this.post(`${resourceName}/parse`, nqlQuery);
         return response;
     }
+    /**
+     * Validates an NQL query and returns an abstract syntax tree (AST) representing a structured form of
+     * the query.
+     *
+     * @param {string} nqlQuery - The NQL query to validate.
+     * @returns {Promise<NqlCompileResult>} A promise that resolves with the result of the NQL validation.
+     */
+    async validateNql(nqlQuery) {
+        const response = await this.post(`${resourceName}/validate`, nqlQuery);
+        return response;
+    }
     /**
      * Gets an existing NQL query by it's id
      *