@narrative.io/data-collaboration-sdk-ts 2.94.1 → 2.95.0-beta.1

package/build/nql/SubstraitParser.d.ts

@@ -0,0 +1,771 @@
+/*!
+Copyright 2023 Narrative I/O, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+NOTICE: THIS FILE HAS BEEN MODIFIED BY NARRATIVE I/O UNDER COMPLIANCE WITH THE APACHE 2.0 LICENCE FROM THE ORIGINAL WORK
+OF THE COMPANY Substrait (https://github.com/substrait-io/substrait-js).
+*/
+type Nullability = "NULLABILITY_UNSPECIFIED" | "NULLABILITY_NULLABLE" | "NULLABILITY_REQUIRED";
+type FailureBehavior = "FAILURE_BEHAVIOR_UNSPECIFIED" | "FAILURE_BEHAVIOR_RETURN_NULL" | "THROW_EXCEPTION";
+interface AdvancedExtension {
+    optimization: unknown;
+    enhancement: unknown;
+}
+type LogicalOperator = "and" | "or" | "not";
+interface Expression {
+    selection?: FieldReference;
+    scalarFunction?: ScalarFunction;
+    literal?: Literal;
+    cast?: CastExpression;
+}
+interface FilterRelation {
+    common: RelCommon;
+    input: Rel;
+    condition: Expression;
+    advancedExtension?: AdvancedExtension;
+}
+interface ProjectRelation {
+    common: RelCommon;
+    input: Rel;
+    expressions: Expression[];
+    advancedExtension?: AdvancedExtension;
+}
+interface JoinRelation {
+    common: RelCommon;
+    left: Rel;
+    right: Rel;
+    expression: Expression;
+    postJoinFilter: Expression;
+    type: JoinType;
+    advancedExtension?: AdvancedExtension;
+}
+interface CrossRelation {
+    common: RelCommon;
+    left: Rel;
+    right: Rel;
+    advancedExtension?: AdvancedExtension;
+}
+interface PlanRelation {
+    rel?: Rel;
+    root?: RelationRoot;
+}
+interface Extension {
+    extensionFunction: ExtensionFunction;
+}
+export interface Plan {
+    version?: Version;
+    extensionUris: ExtensionUri[];
+    extensionUriAnchor?: number;
+    extensions: Extension[];
+    relations: PlanRelation[];
+    advancedExtensions?: AdvancedExtension[];
+    expectedTypeUrls: string[];
+}
+interface Version {
+    major_number: number;
+    minor_number: number;
+    patch_number: number;
+    git_hash?: string;
+    producer?: string;
+}
+interface FetchRelation {
+    common: RelCommon;
+    input: Rel;
+    offset: number;
+    count: number;
+    advancedExtension: AdvancedExtension;
+}
+interface AggregateRelation {
+    common: RelCommon;
+    input: Rel;
+    groupings: Grouping[];
+    measures: Measure[];
+    advancedExtension: AdvancedExtension;
+}
+type FunctionTyp = ScalarFunction | AggregateFunction;
+interface ScalarFunction {
+    functionReference: number;
+    args: FunctionArgument[];
+    options: FunctionOption[];
+    outputType: LiteralType;
+    arguments: FunctionArgument[];
+}
+interface Grouping {
+    groupingExpressions: Expression[];
+}
+interface Measure {
+    measure: AggregateFunction;
+    filter: Expression;
+}
+declare enum AggregationInvocation {
+    AGGREGATION_INVOCATION_UNSPECIFIED = 0,
+    AGGREGATION_INVOCATION_ALL = 1,
+    AGGREGATION_INVOCATION_DISTINCT = 2
+}
+interface EnumTyp {
+    deprecated?: boolean;
+    specified?: string;
+    unspecified?: {
+        deprecated?: boolean;
+    };
+}
+interface FunctionArgument {
+    enum?: EnumTyp;
+    type?: LiteralType;
+    value?: Expression;
+}
+declare enum AggregationPhase {
+    AGGREGATION_PHASE_UNSPECIFIED = 0,
+    AGGREGATION_PHASE_INITIAL_TO_INTERMEDIATE = 1,
+    AGGREGATION_PHASE_INTERMEDIATE_TO_INTERMEDIATE = 2,
+    AGGREGATION_PHASE_INITIAL_TO_RESULT = 3,
+    AGGREGATION_PHASE_INTERMEDIATE_TO_RESULT = 4
+}
+interface FunctionOption {
+    name: string;
+    preference: string[];
+}
+interface AggregateFunction {
+    functionReference: number;
+    arguments: FunctionArgument[];
+    options: FunctionOption[];
+    outputType: LiteralType;
+    phase: AggregationPhase;
+    sorts: SortField[];
+    invocation: AggregationInvocation;
+    args: FunctionArgument[];
+}
+interface SortRelation {
+    common: RelCommon;
+    input: Rel;
+    sorts: SortField[];
+    advancedExtension?: AdvancedExtension;
+}
+interface FilterRelation {
+    common: RelCommon;
+    input: Rel;
+    condition: Expression;
+    advancedExtension?: AdvancedExtension;
+}
+declare enum JoinType {
+    JOIN_TYPE_UNSPECIFIED = 0,
+    JOIN_TYPE_INNER = 1,
+    JOIN_TYPE_OUTER = 2,
+    JOIN_TYPE_LEFT = 3,
+    JOIN_TYPE_RIGHT = 4,
+    JOIN_TYPE_SEMI = 5,
+    JOIN_TYPE_ANTI = 6,
+    JOIN_TYPE_SINGLE = 7
+}
+declare enum SetOp {
+    SET_OP_UNSPECIFIED = 0,
+    SET_OP_MINUS_PRIMARY = 1,
+    SET_OP_MINUS_MULTISET = 2,
+    SET_OP_INTERSECTION_PRIMARY = 3,
+    SET_OP_INTERSECTION_MULTISET = 4,
+    SET_OP_UNION_DISTINCT = 5,
+    SET_OP_UNION_ALL = 6
+}
+interface SetRelation {
+    common: RelCommon;
+    inputs: Rel[];
+    op: SetOp;
+    advancedExtension?: AdvancedExtension;
+}
+interface ExtensionSingleRelation {
+    common: RelCommon;
+    input: Rel;
+    detail: unknown;
+}
+interface ExtensionLeafRelation {
+    common: RelCommon;
+    detail: unknown;
+}
+interface ExtensionMultiRelation {
+    common: RelCommon;
+    inputs: Rel[];
+    detail: unknown;
+}
+interface MaskExpression {
+    select?: {
+        struct?: {
+            structItems: StructItem[];
+        };
+        list?: {
+            selection: ListSelectItem[];
+            child?: Select;
+        };
+        map?: MapSelect;
+    };
+    maintain_singular_struct?: boolean;
+}
+interface StructItem {
+    field: number;
+    child?: StructItem;
+}
+interface ListSelectItem {
+    item?: {
+        field: number;
+    };
+    slice?: {
+        start: number;
+        end: number;
+    };
+}
+interface MapSelect {
+    key: string;
+    child?: Select;
+}
+interface Select {
+    struct?: {
+        struct_items: StructItem[];
+    };
+    list?: {
+        selection: ListSelectItem[];
+        child?: Select;
+    };
+    map?: MapSelect;
+}
+interface ReferenceSegment {
+    mapKey?: {
+        map_key: Literal;
+        child?: ReferenceSegment;
+    };
+    structField?: StructItem;
+    listElement?: {
+        offset: number;
+        child?: ReferenceSegment;
+    };
+}
+interface FieldReference {
+    directReference?: ReferenceSegment;
+    maskedReference?: MaskExpression;
+    expression?: Expression;
+    rootReference?: RootReference;
+    outerReference?: OuterReference;
+}
+type RootReference = unknown;
+interface OuterReference {
+    steps_out: number;
+}
+interface RelationRoot {
+    input: Rel;
+    names: string[];
+}
+interface ScatterFields {
+    fields: FieldReference[];
+}
+interface SingleBucketExpression {
+    expression: Expression;
+}
+interface MultiBucketExpression {
+    expression: Expression;
+    constrained_to_count: boolean;
+}
+interface Broadcast {
+}
+interface RoundRobin {
+    exact: boolean;
+}
+interface ExchangeTarget {
+    partition_id: number[];
+    target_type: string | unknown;
+}
+interface ExchangeRelation {
+    common: RelCommon;
+    input: Rel;
+    partition_count: number;
+    targets: ExchangeTarget[];
+    exchange_kind: ScatterFields | SingleBucketExpression | MultiBucketExpression | RoundRobin | Broadcast;
+    advancedExtension?: AdvancedExtension;
+}
+interface Rel {
+    root?: RelationRoot;
+    filter?: FilterRelation;
+    project?: ProjectRelation;
+    join?: JoinRelation;
+    cross?: CrossRelation;
+    fetch?: FetchRelation;
+    aggregate?: AggregateRelation;
+    sort?: SortRelation;
+    set?: SetRelation;
+    single?: ExtensionSingleRelation;
+    leaf?: ExtensionLeafRelation;
+    multi?: ExtensionMultiRelation;
+    exchange?: ExchangeRelation;
+    read?: ReadRelation;
+}
+interface CastExpression {
+    type: LiteralType;
+    input: Expression;
+    failureBehavior: FailureBehavior;
+}
+declare enum SortDirection {
+    UNSPECIFIED = 0,
+    ASCENDING_NULLS_FIRST = 1,
+    ASCENDING_NULLS_LAST = 2,
+    DESCENDING_NULLS_FIRST = 3,
+    DESCENDING_NULLS_LAST = 4,
+    CLUSTERED = 5
+}
+interface SortField {
+    expr: Expression;
+    direction: SortDirection;
+}
+interface Literal extends LiteralType {
+    nullable: boolean;
+    typeVariationReference: number;
+}
+interface LiteralType {
+    bool?: BoolTyp;
+    i8?: number;
+    i16?: number;
+    i32?: I32;
+    i64?: I64;
+    fp32?: number;
+    fp64?: FP64;
+    string?: StrType;
+    binary?: Uint8Array;
+    timestamp?: number;
+    date?: Date;
+    time?: number;
+    intervalYearToMonth?: IntervalYearToMonth;
+    intervalDayToSecond?: IntervalDayToSecond;
+    fixedChar?: FixedChar | string;
+    varchar?: VarChar;
+    fixedBinary?: FixedBinary;
+    decimal?: Decimal;
+    struct?: Struct;
+    map?: MapTyp;
+    timestampTz?: TimestampTz;
+    uuid?: Uint8Array;
+    null?: unknown;
+    list?: List;
+    empty_list?: unknown;
+    empty_map?: unknown;
+    user_defined?: unknown;
+}
+interface FixedBinary {
+    typeVariationReference: number;
+    value?: Uint8Array;
+    length: number;
+    nullability: Nullability;
+}
+interface TimestampTz {
+    typeVariationReference: number;
+    value?: number;
+    nullability: Nullability;
+}
+interface BoolTyp {
+    typeVariationReference: number;
+    value?: boolean;
+    nullability: Nullability;
+}
+interface StrType {
+    typeVariationReference: number;
+    value?: string;
+    nullability: Nullability;
+}
+interface I32 {
+    typeVariationReference: number;
+    value?: number;
+    nullability: Nullability;
+}
+interface FP64 {
+    typeVariationReference: number;
+    value?: number;
+    nullability: Nullability;
+}
+interface I64 {
+    typeVariationReference: number;
+    value?: number;
+    nullability: Nullability;
+}
+interface Date {
+    typeVariationReference: number;
+    nullability: Nullability;
+    value?: number;
+}
+interface FixedChar {
+    typeVariationReference: number;
+    value?: string;
+    length: number;
+    nullability: Nullability;
+}
+interface VarChar {
+    typeVariationReference: number;
+    value?: string;
+    length: number;
+    nullability: Nullability;
+}
+interface Decimal {
+    value?: string;
+    precision: number;
+    scale: number;
+    nullability?: Nullability;
+    typeVariationReference?: number;
+}
+interface MapTyp {
+    typeVariationReference: number;
+    key_values: KeyValue[];
+}
+interface KeyValue {
+    key: Literal;
+    value: Literal;
+}
+interface IntervalYearToMonth {
+    typeVariationReference: number;
+    years: number;
+    months: number;
+}
+interface IntervalDayToSecond {
+    typeVariationReference: number;
+    days: number;
+    seconds: number;
+    microseconds: number;
+}
+interface List {
+    type: LiteralType;
+    typeVariationReference: number;
+    values?: Literal[];
+    nullability: Nullability;
+}
+interface ExtensionUri {
+    extensionUriAnchor: number;
+    uri: string;
+}
+interface Extension {
+    extensionFunction: ExtensionFunction;
+}
+interface NamedTable {
+    names: string[];
+}
+interface SimpleProperty {
+    name: string;
+    value: string;
+}
+interface NamedStruct {
+    names: string[];
+    struct: Struct;
+}
+interface Stats {
+    row_count: number;
+    record_size: number;
+    advancedExtension?: AdvancedExtension;
+}
+interface RuntimeConstraint {
+    advancedExtension?: AdvancedExtension;
+}
+interface Hint {
+    stats: Stats;
+    constraint: RuntimeConstraint;
+    advancedExtension?: AdvancedExtension;
+}
+interface RelCommon {
+    emit?: Emit;
+    hint?: Hint;
+    advancedExtension?: AdvancedExtension;
+    direct?: unknown;
+}
+interface Struct {
+    types: LiteralType[];
+    nullability: Nullability;
+    typeVariationReference: number;
+    fields?: Literal[];
+}
+interface Emit {
+    outputMapping: number[];
+}
+interface ReadRelation {
+    namedTable: NamedTable;
+    baseSchema: NamedStruct;
+    common: RelCommon;
+}
+interface ExtensionFunction {
+    functionAnchor: number;
+    name: string;
+    extensionUriReference: number;
+}
+interface Field {
+    name: string;
+    type: string;
+    nullability: Nullability;
+    children: Field[];
+}
+interface PrintNode {
+    id: string;
+    type: string;
+    inputs: PrintNode[];
+    props: SimpleProperty[];
+    schema: Field;
+}
+declare class SubstraitParser {
+    idCounters: Map<string, number>;
+    extSet: Map<number, string>;
+    fieldNames: string[];
+    selectedFields: string[];
+    filters: string[];
+    logicalOperators: LogicalOperator[];
+    /**
+     * Constructs a SubstraitParser
+     * @param {SubstraitPlan} plan the Substrait plan
+     */
+    constructor(plan: Plan);
+    /**
+     * Creates a map from anchor to function name
+     * @param {SubstraitPlan} plan the Substrait plan
+     * @return {Map<number, string>} the created mapping
+     */
+    buildExtensionSet(plan: Plan): Map<number, string>;
+    /**
+     * Geneate a unique id for the node
+     * @param {string} type The type of the node
+     * @return {string} A unique id
+     */
+    nextId(type: string): string;
+    /**
+     * Create a schema field
+     *
+     * This is a special field with an empty name and an empty type string
+     * and uknown nullability
+     *
+     * @param {Field[]} fields the fields of the schema
+     * @return {Field} a schema field
+     */
+    makeSchemaField(fields: Field[]): Field;
+    /**
+     * Applies a Substrait emit to an output schema
+     * @param {Field} schema the original output schema
+     * @param {Object} emit a potential remapping of fields
+     * @return {Field} the remapped output schema
+     */
+    applyEmit(schema: Field, emit?: Emit): Field;
+    /**
+     * Create a print node, generating a new id
+     *
+     * @param {string} type the node type
+     * @param {PrintNode[]} inputs the inputs to the node
+     * @param {SimpleProperty[]} props properties describing the node
+     * @param {Field} schema the output schema of the node
+     * @param {Object} emit the Substrait emit for the node
+     * @return {PrintNode} a print node
+     */
+    makePrintNode(type: string, inputs: PrintNode[], props: SimpleProperty[], schema: Field, emit?: Emit): PrintNode;
+    /**
+     * Recursive helper for structFieldToStr
+     * @param {*} field the Substrait field to convert
+     * @param {*} currentName the current name
+     * @param {Field} currentField the current input field
+     * @return {Field} a stringified represenstation
+     */
+    structFieldHelper(field: StructItem, currentName: string, currentField: Field): Field;
+    /**
+     * Convert a struct field to a stringified representation
+     *
+     * Struct fields are usually intuitively written with names.
+     * For example, a.b.c.   However, fields in Substrait plans
+     * are not typically named.  So instead we represent them as
+     * $0, $1, $2, ... where $N means the field at index N.
+     *
+     * If the field does happen to be named we will use that.
+     *
+     * @param {StructItem} field a Substrait struct field
+     * @param {Field} exprIn the input to the expression
+     * @return {Field} a stringified representation
+     */
+    structFieldToField(field: StructItem, exprIn: Field): Field;
+    /**
+     * Convert a direct reference to a stringified representation
+     * @param {Object} ref A Substrait direct reference
+     * @param {Object} exprIn the input to the expression
+     * @return {Field} a string representation
+     */
+    directReferenceToField(ref: ReferenceSegment, exprIn: Field): Field;
+    /**
+     * Convert a reference to a stringified representation
+     * @param {Object} ref A Substrait reference expression
+     * @param {Object} exprIn the input to the expression
+     * @return {Field} a string representation
+     */
+    referenceToField(ref: FieldReference, exprIn: Field): Field;
+    /**
+     * Convert a Substrait function argument to a string
+     * @param {Object} arg the argument to convert
+     * @param {Field} inp the input field
+     * @return {string} a string representation
+     */
+    functionArgumentToStr(arg: FunctionArgument, inp: Field): string;
+    /**
+     * Converts a Substrait function reference to a string
+     * @param {number} ref a Substrait function reference
+     * @return {string} a string version of the reference
+     */
+    functionRefToName(ref: number): string;
+    /**
+     * Convert arguments to a joined string
+     * @param {FunctionTyp} func A Substrait function call
+     * @param {Field} schema The input type
+     * @return {string} A string representation
+     */
+    argsToString(func: FunctionTyp, schema: Field): string;
+    /**
+     * Convert a scalar function to a stringified representation
+     * @param {Object} func the function to convert
+     * @param {Field} schema the input type info
+     * @return {Field} a string version of the function
+     */
+    scalarFunctionToField(func: ScalarFunction, schema: Field): Field;
+    /**
+     * Converts a Substrait literal to a field
+     * @param {Object} lit the Substrait literal
+     * @return {Field} a field representation
+     */
+    literalToField(lit: Literal): Field;
+    /**
+     * Convert a cast expression to a stringified representation
+     * @param {Object} cast A Substrait cast expression
+     * @param {Field} schema The input schema
+     * @return {Field} A field representation
+     */
+    castToField(cast: CastExpression, schema: Field): Field;
+    /**
+     * Convert an expression to a stringified representation
+     *
+     * The expression is returned as a field where the type
+     * of the field is the output type of the expression and the
+     * name of the field is a string representation of the expression
+     *
+     * @param {Object} expr A Substrait expression
+     * @param {Object} exprIn the input to the expression
+     * @return {Field} a string representation
+     */
+    expressionToStr(expr: Expression, exprIn: Field): Field;
+    /**
+     * Convert a project relation to a print node
+     * @param {Object} project A Substrait ProjectRel
+     * @return {PrintNode} a print node
+     */
+    projectToNode(project: ProjectRelation): PrintNode;
+    /**
+     * Convert a Substrait data type to an unnamed Field
+     *
+     * The field's name will be an empty string
+     *
+     * @param {Object} type a Substrait data type
+     * @return {Field} an unnamed field
+     */
+    typeToField(type: LiteralType): Field;
+    /**
+     * Convert a named struct to an array of Field
+     * @param {NamedStruct} struct a Substrait named struct
+     * @return {Field[]} named fields
+     */
+    namedStructToSchema(struct: NamedStruct): Field;
+    /**
+     * Extract the properties from a read relation
+     * @param {Object} read a Substrait read relation
+     * @return {SimpleProperty[]} properties for the relation
+     */
+    readTypeToProps(read: ReadRelation): SimpleProperty[];
+    /**
+     * Convert a Substrait read relation to a print node
+     * @param {Object} read a Substrait read relation
+     * @return {PrintNode} a print node
+     */
+    readToNode(read: ReadRelation): PrintNode;
+    /**
+     * True if the object has a field with the given name
+     * @param {Object} obj the object to test
+     * @param {string} fieldName the field name to look for
+     * @return {boolean} the result of the test
+     */
+    hasValue(obj: object, fieldName: string): boolean;
+    /**
+     * Convert a Substrait fetch relation to a print node
+     * @param {Object} fetch a Substrait fetch relation
+     * @return {PrintNode} a print node
+     */
+    fetchToNode(fetch: FetchRelation): PrintNode;
+    /**
+     * Convert a Substrait sort field to a property
+     * @param {Object} sortField a Substrait sort field
+     * @param {Field} schema the schema of the sort input
+     * @return {SimpleProperty} a property describing the sort
+     */
+    sortFieldToStr(sortField: SortField, schema: Field): string | undefined;
+    /**
+     * Convert a Substrait sort relation to a print node
+     * @param {Object} sort a Substrait sort relation
+     * @return {PrintNode} a print node
+     */
+    sortToNode(sort: SortRelation): PrintNode;
+    /**
+     * Convert a Substrait aggregate function to a field
+     * @param {Object} func the Substrait aggregate function
+     * @param {Field} inp the input field
+     * @return {Field} a field representation of the function
+     */
+    aggregateFunctionToField(func: AggregateFunction, inp: Field): Field;
+    /**
+     * Convert a Substrait aggregate relation to a print node
+     * @param {Object} agg a Substrait aggregate relation
+     * @return {PrintNode} a print node
+     */
+    aggToNode(agg: AggregateRelation): PrintNode;
+    /**
+     * Convert a Substrait filter relation to a print node
+     * @param {Object} filt a Substrait filter relation
+     * @return {PrintNode} a print node
+     */
+    filterToNode(filt: FilterRelation): PrintNode;
+    /**
+     * Converts a Substrait join relation to a print node
+     * @param {Object} join a Substrait join relation
+     * @return {PrintNode} a print node
+     */
+    joinToNode(join: JoinRelation): PrintNode;
+    /**
+     * Converts a Substrait relation to a print node
+     * @param {Object} rel the Substrait relation to convert
+     * @return {PrintNode} a print node
+     */
+    relToNode(rel: Rel): PrintNode;
+    /**
+     * Converts a Substrait root relation to a print node
+     * @param {Object} rel the Substrait relation to convert
+     * @return {PrintNode} a print node
+     */
+    rootRelToNode(rel: RelationRoot): PrintNode;
+    /**
+     * Converts a Substrait plan to a print node
+     * @param {Object} plan the Substrait plan to convert
+     * @return {PrintNode} a print node
+     */
+    planToNode(plan: Plan): PrintNode;
+    parse(plan: Plan): {
+        selection: string[];
+        filters: string[];
+        logicalOperators: LogicalOperator[];
+    };
+    /**
+     * Converts a base64 string into a decimal number.
+     *
+     * @public
+     * @param {string} base64 - The base64 string to convert.
+     * @param {number} precision - The total number of digits in the output number.
+     * @param {number} scale - The number of digits after the decimal point in the output number.
+     * @throws {Error} Will throw an error if the conversion fails.
+     * @returns {number} The converted decimal number.
+     * @example
+     * // returns 123.45
+     * this.base64ToDecimal('MTIzNDU=', 5, 2);
+     */
+    base64ToDecimal(base64: string, precision: number, scale: number): number;
+    private deduplicate;
+}
+export { SubstraitParser };