@malloydata/malloy-interfaces 0.0.78-dev230818010117

package/dist/model/malloy_types.d.ts

@@ -0,0 +1,674 @@
+/// <reference types="node" />
+interface ParamBase {
+    name: string;
+    type: AtomicFieldType;
+}
+declare type ConstantExpr = Expr;
+declare type Condition = Expr;
+interface ParamCondition extends ParamBase {
+    condition: Condition | null;
+}
+interface ParamValue extends ParamBase {
+    value: ConstantExpr | null;
+    constant: boolean;
+}
+export declare type Parameter = ParamCondition | ParamValue;
+export declare function isValueParameter(p: Parameter): p is ParamValue;
+export declare function isConditionParameter(p: Parameter): p is ParamCondition;
+export declare function paramHasValue(p: Parameter): boolean;
+export interface DocumentRange {
+    start: DocumentPosition;
+    end: DocumentPosition;
+}
+export interface DocumentPosition {
+    line: number;
+    character: number;
+}
+export interface ImportLocation {
+    importURL: string;
+    location: DocumentLocation;
+}
+export interface DocumentLocation {
+    url: string;
+    range: DocumentRange;
+}
+interface DocumentReferenceBase {
+    text: string;
+    location: DocumentLocation;
+    definition: HasLocation;
+}
+export interface DocumentExploreReference extends DocumentReferenceBase {
+    type: 'exploreReference';
+    definition: StructDef;
+}
+export interface DocumentJoinReference extends DocumentReferenceBase {
+    type: 'joinReference';
+    definition: FieldDef;
+}
+export interface DocumentSQLBlockReference extends DocumentReferenceBase {
+    type: 'sqlBlockReference';
+    definition: SQLBlockStructDef;
+}
+export interface DocumentQueryReference extends DocumentReferenceBase {
+    type: 'queryReference';
+    definition: Query;
+}
+export interface DocumentFieldReference extends DocumentReferenceBase {
+    type: 'fieldReference';
+    definition: FieldDef;
+}
+export declare type DocumentReference = DocumentExploreReference | DocumentQueryReference | DocumentSQLBlockReference | DocumentFieldReference | DocumentJoinReference;
+/** put location into the parse tree. */
+export interface HasLocation {
+    location?: DocumentLocation;
+}
+/** All names have their source names and how they will appear in the symbol table that owns them */
+export interface AliasedName {
+    name: string;
+    as?: string;
+}
+export interface TypedObject {
+    type: string;
+}
+export interface FilteredAliasedName extends AliasedName {
+    filterList?: FilterExpression[];
+}
+export declare function isFilteredAliasedName(f: FieldTypeRef): f is FilteredAliasedName;
+/** all named objects have a type an a name (optionally aliased) */
+export interface NamedObject extends AliasedName, HasLocation {
+    type: string;
+}
+export interface ResultMetadataDef {
+    sourceField: string;
+    sourceExpression?: string;
+    sourceClasses: string[];
+    filterList?: FilterExpression[];
+    fieldKind: 'measure' | 'dimension' | 'struct';
+}
+export interface ResultStructMetadataDef extends ResultMetadataDef {
+    limit?: number;
+    orderBy?: OrderBy[];
+}
+export interface ResultMetadata {
+    resultMetadata?: ResultMetadataDef;
+}
+export interface ResultStructMetadata {
+    resultMetadata?: ResultStructMetadataDef;
+}
+export interface OutputFieldFragment {
+    type: 'outputField';
+    name: string;
+}
+export declare function isOutputFieldFragment(f: Fragment): f is OutputFieldFragment;
+export interface FilterFragment {
+    type: 'filterExpression';
+    filterList: FilterExpression[];
+    e: Expr;
+}
+export declare function isFilterFragment(f: Fragment): f is FilterFragment;
+export declare function isDialectFragment(f: Fragment): f is DialectFragment;
+export interface AggregateFragment {
+    type: 'aggregate';
+    function: string;
+    e: Expr;
+    structPath?: string;
+}
+export declare function isAggregateFragment(f: Fragment): f is AggregateFragment;
+export declare function isAsymmetricFragment(f: Fragment): f is AggregateFragment;
+export interface UngroupFragment {
+    type: 'all' | 'exclude';
+    e: Expr;
+    fields?: string[];
+}
+export declare function isUngroupFragment(f: Fragment): f is UngroupFragment;
+export interface FunctionParameterFragment {
+    type: 'function_parameter';
+    name: string;
+}
+export declare function isFunctionParameterFragment(f: Fragment): f is FunctionParameterFragment;
+export interface FunctionCallFragment {
+    type: 'function_call';
+    overload: FunctionOverloadDef;
+    expressionType: ExpressionType;
+    args: Expr[];
+    structPath?: string;
+}
+export declare function isFunctionCallFragment(f: Fragment): f is FunctionCallFragment;
+export interface SQLExpressionFragment {
+    type: 'sql_expression';
+    e: Expr;
+}
+export declare function isSQLExpressionFragment(f: Fragment): f is SQLExpressionFragment;
+export interface SpreadFragment {
+    type: 'spread';
+    e: Expr;
+}
+export declare function isSpreadFragment(f: Fragment): f is SpreadFragment;
+export interface FieldFragment {
+    type: 'field';
+    path: string;
+}
+export declare function isFieldFragment(f: Fragment): f is FieldFragment;
+export interface ParameterFragment {
+    type: 'parameter';
+    path: string;
+}
+export declare function isParameterFragment(f: Fragment): f is ParameterFragment;
+export interface ApplyValueFragment {
+    type: 'applyVal';
+}
+export declare function isApplyValue(f: Fragment): f is ApplyValueFragment;
+export interface ApplyFragment {
+    type: 'apply';
+    value: Expr;
+    to: Expr;
+}
+export declare function isApplyFragment(f: Fragment): f is ApplyFragment;
+interface DialectFragmentBase {
+    type: 'dialect';
+    function: string;
+}
+export interface NowFragment extends DialectFragmentBase {
+    function: 'now';
+}
+export interface TimeDiffFragment extends DialectFragmentBase {
+    function: 'timeDiff';
+    units: TimestampUnit;
+    left: TimeValue;
+    right: TimeValue;
+}
+export interface TimeDeltaFragment extends DialectFragmentBase {
+    function: 'delta';
+    base: TimeValue;
+    op: '+' | '-';
+    delta: Expr;
+    units: TimestampUnit;
+}
+export interface TimeTruncFragment extends DialectFragmentBase {
+    function: 'trunc';
+    expr: TimeValue;
+    units: TimestampUnit;
+}
+export interface TimeExtractFragment extends DialectFragmentBase {
+    function: 'extract';
+    expr: TimeValue;
+    units: ExtractUnit;
+}
+export interface TypecastFragment extends DialectFragmentBase {
+    function: 'cast';
+    safe: boolean;
+    expr: Expr;
+    dstType: AtomicFieldType;
+    srcType?: AtomicFieldType;
+}
+export interface RegexpMatchFragment extends DialectFragmentBase {
+    function: 'regexpMatch';
+    expr: Expr;
+    regexp: Expr;
+}
+export interface DivFragment extends DialectFragmentBase {
+    function: 'div';
+    numerator: Expr;
+    denominator: Expr;
+}
+export interface TimeLiteralFragment extends DialectFragmentBase {
+    function: 'timeLiteral';
+    literal: string;
+    literalType: TimeFieldType;
+    timezone?: string;
+}
+export interface StringLiteralFragment extends DialectFragmentBase {
+    function: 'stringLiteral';
+    literal: string;
+}
+export interface RegexpLiteralFragment extends DialectFragmentBase {
+    function: 'regexpLiteral';
+    literal: string;
+}
+export interface NumberLiteralFragment extends DialectFragmentBase {
+    function: 'numberLiteral';
+    literal: string;
+}
+export declare type DialectFragment = DivFragment | TimeLiteralFragment | NowFragment | TimeDeltaFragment | TimeDiffFragment | TimeTruncFragment | TypecastFragment | TimeExtractFragment | StringLiteralFragment | RegexpLiteralFragment | NumberLiteralFragment | RegexpMatchFragment;
+export declare type Fragment = string | ApplyFragment | ApplyValueFragment | FieldFragment | ParameterFragment | FilterFragment | OutputFieldFragment | AggregateFragment | UngroupFragment | DialectFragment | FunctionParameterFragment | FunctionCallFragment | SQLExpressionFragment | SpreadFragment;
+export declare type Expr = Fragment[];
+export interface TypedValue {
+    value: Expr;
+    valueType: AtomicFieldType;
+}
+export interface TimeValue extends TypedValue {
+    valueType: TimeFieldType;
+}
+declare type TagElement = Expr | string;
+/**
+ * Return an Expr based on the string template, subsittutions can be
+ * either strings, or other Exprs.
+
+ * ```
+ * units = "inches"
+ * len: Expr = [ "something", "returning", "a length "]
+ * computeExpr = mkExpr`MEASURE(${len} in ${units})`;
+ * ```
+ */
+export declare function mkExpr(src: TemplateStringsArray, ...exprs: TagElement[]): Expr;
+export declare type ExpressionType = 'scalar' | 'aggregate' | 'scalar_analytic' | 'aggregate_analytic' | 'ungrouped_aggregate';
+export interface Expression {
+    e?: Expr;
+    expressionType?: ExpressionType;
+    code?: string;
+}
+export declare function expressionIsScalar(e: ExpressionType | undefined): boolean;
+export declare function expressionIsAggregate(e: ExpressionType | undefined): boolean;
+export declare function expressionIsUngroupedAggregate(e: ExpressionType | undefined): boolean;
+export declare function expressionInvolvesAggregate(e: ExpressionType | undefined): boolean;
+export declare function expressionIsCalculation(e: ExpressionType | undefined): boolean;
+export declare function expressionIsAnalytic(e: ExpressionType | undefined): boolean;
+export declare function isExpressionTypeLEQ(e1: ExpressionType, e2: ExpressionType): boolean;
+export declare function maxExpressionType(e1: ExpressionType, e2: ExpressionType): ExpressionType;
+export declare function maxOfExpressionTypes(types: ExpressionType[]): ExpressionType;
+interface JustExpression {
+    e: Expr;
+}
+declare type HasExpression = FieldDef & JustExpression;
+/**  Grants access to the expression property of a FieldDef */
+export declare function hasExpression(f: FieldDef): f is HasExpression;
+export declare type TimeFieldType = 'date' | 'timestamp';
+export declare function isTimeFieldType(s: string): s is TimeFieldType;
+export declare type AtomicFieldType = 'string' | 'number' | TimeFieldType | 'boolean' | 'unsupported' | 'json' | 'error';
+export declare function isAtomicFieldType(s: string): s is AtomicFieldType;
+/**
+ * Fields which contain scalar data all inherit from this. The field
+ * value could be an expression, and this is one of the objects
+ * which might have an annotation.
+ */
+export interface FieldAtomicDef extends NamedObject, Expression, ResultMetadata {
+    type: AtomicFieldType;
+    annotation?: Annotation;
+}
+export declare function FieldIsIntrinsic(f: FieldDef): boolean;
+/** Scalar String Field */
+export interface FieldStringDef extends FieldAtomicDef {
+    type: 'string';
+    bucketFilter?: string;
+    bucketOther?: string;
+}
+/** Scalar Numeric String Field */
+export interface FieldNumberDef extends FieldAtomicDef {
+    type: 'number';
+    numberType?: 'integer' | 'float';
+}
+/** Scalar Boolean Field */
+export interface FieldBooleanDef extends FieldAtomicDef {
+    type: 'boolean';
+}
+/** Scalar JSON Field */
+export interface FieldJSONDef extends FieldAtomicDef {
+    type: 'json';
+}
+/** Scalar unsupported Field */
+export interface FieldUnsupportedDef extends FieldAtomicDef {
+    type: 'unsupported';
+    rawType?: string;
+}
+export interface FieldErrorDef extends FieldAtomicDef {
+    type: 'error';
+}
+export declare type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
+export declare function isDateUnit(str: string): str is DateUnit;
+export declare type TimestampUnit = DateUnit | 'hour' | 'minute' | 'second';
+export declare function isTimestampUnit(s: string): s is TimestampUnit;
+export declare type ExtractUnit = TimestampUnit | 'day_of_week' | 'day_of_year';
+export declare function isExtractUnit(s: string): s is ExtractUnit;
+/** Value types distinguished by their usage in generated SQL, particularly with respect to filters. */
+export declare enum ValueType {
+    Date = "date",
+    Timestamp = "timestamp",
+    Number = "number",
+    String = "string"
+}
+export declare type TimeValueType = ValueType.Date | ValueType.Timestamp;
+/** Scalar Date Field. */
+export interface FieldDateDef extends FieldAtomicDef {
+    type: 'date';
+    timeframe?: DateUnit;
+}
+/** Scalar Timestamp Field */
+export interface FieldTimestampDef extends FieldAtomicDef {
+    type: 'timestamp';
+    timeframe?: TimestampUnit;
+}
+/** parameter to order a query */
+export interface OrderBy {
+    field: string | number;
+    dir?: 'asc' | 'desc';
+}
+export interface ByName {
+    by: 'name';
+    name: string;
+}
+export interface ByExpression {
+    by: 'expression';
+    e: Expr;
+}
+export declare type By = ByName | ByExpression;
+export declare function isByName(by: By | undefined): by is ByName;
+export declare function isByExpression(by: By | undefined): by is ByExpression;
+/** reference to a data source */
+export declare type StructRef = string | StructDef;
+export declare function refIsStructDef(ref: StructRef): ref is StructDef;
+/** join pattern structs is a struct. */
+export interface JoinedStruct {
+    structRef: StructRef;
+    structRelationship: StructRelationship;
+    as: string;
+}
+export interface Filtered {
+    filterList?: FilterExpression[];
+}
+/**
+ * First element in a pipeline might be a reference to a turtle
+ */
+export interface TurtleSegment extends Filtered {
+    name: string;
+}
+export interface Pipeline {
+    pipeHead?: TurtleSegment;
+    pipeline: PipeSegment[];
+}
+export interface Query extends Pipeline, Filtered, HasLocation {
+    type?: 'query';
+    structRef: StructRef;
+    annotation?: Annotation;
+    modelAnnotation?: Annotation;
+}
+export declare type NamedQuery = Query & NamedObject;
+export declare type PipeSegment = QuerySegment | IndexSegment;
+export interface ReduceSegment extends QuerySegment {
+    type: 'reduce';
+}
+export declare function isReduceSegment(pe: PipeSegment): pe is ReduceSegment;
+export interface ProjectSegment extends QuerySegment {
+    type: 'project';
+}
+export declare function isProjectSegment(pe: PipeSegment): pe is ProjectSegment;
+export declare function isQuerySegment(pe: PipeSegment): pe is QuerySegment;
+export declare type Sampling = SamplingRows | SamplingEnable | SamplingPercent;
+interface SamplingRows {
+    rows: number;
+}
+export declare function isSamplingRows(s: Sampling): s is SamplingRows;
+interface SamplingPercent {
+    percent: number;
+}
+export declare function isSamplingPercent(s: Sampling): s is SamplingPercent;
+interface SamplingEnable {
+    enable: boolean;
+}
+export declare function isSamplingEnable(s: Sampling): s is SamplingEnable;
+export interface IndexSegment extends Filtered {
+    type: 'index';
+    fields: string[];
+    limit?: number;
+    weightMeasure?: string;
+    sample?: Sampling;
+}
+export declare function isIndexSegment(pe: PipeSegment): pe is IndexSegment;
+export interface QuerySegment extends Filtered {
+    type: 'reduce' | 'project';
+    fields: QueryFieldDef[];
+    extendSource?: FieldDef[];
+    limit?: number;
+    by?: By;
+    orderBy?: OrderBy[];
+    queryTimezone?: string;
+}
+export interface TurtleDef extends NamedObject, Pipeline {
+    type: 'turtle';
+    annotation?: Annotation;
+}
+export declare type JoinRelationship = 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
+export interface JoinOn {
+    type: 'one' | 'many' | 'cross';
+    onExpression?: Expr;
+}
+export declare function isJoinOn(sr: StructRelationship): sr is JoinOn;
+/** types of joins. */
+export declare type StructRelationship = {
+    type: 'basetable';
+    connectionName: string;
+} | JoinOn | {
+    type: 'inline';
+} | {
+    type: 'nested';
+    field: FieldRef;
+    isArray: boolean;
+};
+export interface SQLFragment {
+    sql: string;
+}
+export declare type SQLPhrase = Query | SQLFragment;
+export declare function isSQLFragment(f: SQLPhrase): f is SQLFragment;
+/**
+ * A source reference to an SQL block. The compiler uses these to request
+ * an SQLBlock with it's schema and structdef defined. Use the factory
+ * makeSQLBlock to construct these.
+ */
+export interface SQLBlockSource {
+    name: string;
+    connection?: string;
+    select: SQLPhrase[];
+}
+export interface SQLBlock extends NamedObject {
+    type: 'sqlBlock';
+    connection?: string;
+    selectStr: string;
+}
+interface SubquerySource {
+    type: 'sql';
+    method: 'subquery';
+    sqlBlock: SQLBlock;
+}
+/** where does the struct come from? */
+export declare type StructSource = {
+    type: 'table';
+    tablePath: string;
+} | {
+    type: 'nested';
+} | {
+    type: 'inline';
+} | {
+    type: 'query';
+    query: Query;
+} | {
+    type: 'sql';
+    method: 'nested' | 'lastStage';
+} | {
+    type: 'query_result';
+} | SubquerySource;
+/** struct that is intrinsic to the table */
+export interface StructDef extends NamedObject, ResultStructMetadata, Filtered {
+    type: 'struct';
+    structSource: StructSource;
+    structRelationship: StructRelationship;
+    fields: FieldDef[];
+    primaryKey?: PrimaryKeyRef;
+    parameters?: Record<string, Parameter>;
+    queryTimezone?: string;
+    dialect: string;
+    annotation?: Annotation;
+    modelAnnotation?: ModelAnnotation;
+}
+export declare type ExpressionValueType = AtomicFieldType | 'null' | 'duration' | 'any' | 'regular expression';
+export declare type FieldValueType = ExpressionValueType | 'turtle' | 'struct';
+export interface ExpressionTypeDesc {
+    dataType: FieldValueType;
+    expressionType: ExpressionType;
+    rawType?: string;
+    evalSpace: EvalSpace;
+}
+export interface FunctionParamTypeDesc {
+    dataType: FieldValueType;
+    expressionType: ExpressionType | undefined;
+    evalSpace: EvalSpace;
+}
+export declare type EvalSpace = 'constant' | 'input' | 'output' | 'literal';
+export declare function mergeEvalSpaces(...evalSpaces: EvalSpace[]): EvalSpace;
+export interface TypeDesc {
+    dataType: FieldValueType;
+    expressionType: ExpressionType;
+    rawType?: string;
+    evalSpace: EvalSpace;
+}
+export interface FunctionParameterDef {
+    name: string;
+    allowedTypes: FunctionParamTypeDesc[];
+    isVariadic: boolean;
+}
+export interface FunctionOverloadDef {
+    returnType: TypeDesc;
+    needsWindowOrderBy?: boolean;
+    between?: {
+        preceding: number | string;
+        following: number | string;
+    };
+    params: FunctionParameterDef[];
+    dialect: {
+        [dialect: string]: Expr;
+    };
+}
+export interface FunctionDef extends NamedObject {
+    type: 'function';
+    overloads: FunctionOverloadDef[];
+}
+export interface ConnectionDef extends NamedObject {
+    type: 'connection';
+}
+export interface SQLBlockStructDef extends StructDef {
+    structSource: SubquerySource;
+    declaredSQLBlock?: boolean;
+}
+export declare function isSQLBlockStruct(sd: StructDef): sd is SQLBlockStructDef;
+/** any of the different field types */
+export declare type FieldTypeDef = FieldStringDef | FieldDateDef | FieldTimestampDef | FieldNumberDef | FieldBooleanDef | FieldJSONDef | FieldUnsupportedDef | FieldErrorDef;
+export declare function isFieldTypeDef(f: FieldDef): f is FieldTypeDef;
+export declare function isFieldTimeBased(f: FieldDef): f is FieldTimestampDef | FieldDateDef;
+export declare function isFieldStructDef(f: FieldDef): f is StructDef;
+/** field reference in a query */
+export declare type FieldTypeRef = string | FieldTypeDef | FilteredAliasedName;
+/** field reference with with possibly and order by. */
+export declare type QueryFieldDef = FieldTypeRef | TurtleDef;
+/** basics statement */
+export declare type FieldDef = FieldTypeDef | StructDef | TurtleDef;
+/** reference to a field */
+export declare type FieldRef = string | FieldDef;
+/** which field is the primary key in this struct */
+export declare type PrimaryKeyRef = string;
+/** filters */
+export interface FilterExpression {
+    expression: Expr;
+    code: string;
+    expressionType: ExpressionType;
+}
+/** Get the output name for a NamedObject */
+export declare function getIdentifier(n: AliasedName): string;
+export declare type NamedModelObject = StructDef | NamedQuery | FunctionDef | ConnectionDef;
+/** Result of parsing a model file */
+export interface ModelDef {
+    name: string;
+    exports: string[];
+    contents: Record<string, NamedModelObject>;
+    annotation?: ModelAnnotation;
+}
+/** Very common record type */
+export declare type NamedStructDefs = Record<string, StructDef>;
+export declare type NamedModelObjects = Record<string, NamedModelObject>;
+/** Malloy source annotations attached to objects */
+export interface Annotation {
+    inherits?: Annotation;
+    blockNotes?: Note[];
+    notes?: Note[];
+}
+export interface Note {
+    text: string;
+    at: DocumentLocation;
+}
+/** Annotations with a uuid to make it easier to stream */
+export interface ModelAnnotation extends Annotation {
+    id: string;
+}
+export declare type QueryScalar = string | boolean | number | Date | Buffer | null;
+/** One value in one column of returned data. */
+export declare type QueryValue = QueryScalar | QueryData | QueryDataRow;
+/** A row of returned data. */
+export declare type QueryDataRow = {
+    [columnName: string]: QueryValue;
+};
+/** Returned query data. */
+export declare type QueryData = QueryDataRow[];
+/** Query execution stats. */
+export declare type QueryRunStats = {
+    queryCostBytes?: number;
+};
+/** Returned Malloy query data */
+export declare type MalloyQueryData = {
+    rows: QueryDataRow[];
+    totalRows: number;
+    runStats?: QueryRunStats;
+};
+export interface DrillSource {
+    sourceExplore: string;
+    sourceFilters?: FilterExpression[];
+}
+export interface CompiledQuery extends DrillSource {
+    structs: StructDef[];
+    sql: string;
+    lastStageName: string;
+    malloy: string;
+    queryName?: string | undefined;
+    connectionName: string;
+    queryTimezone?: string;
+    annotation?: Annotation;
+}
+/** Result type for running a Malloy query. */
+export interface QueryResult extends CompiledQuery {
+    result: QueryData;
+    totalRows: number;
+    error?: string;
+    runStats?: QueryRunStats;
+}
+export declare function isTurtleDef(def: FieldDef): def is TurtleDef;
+export interface SearchResultRow {
+    field_name: string;
+    field_value: string;
+    weight: number;
+}
+export declare type SearchResult = SearchResultRow[];
+export declare function isDimensional(field: FieldDef): boolean;
+export declare function isPhysical(field: FieldDef): boolean;
+export declare function getDimensions(structDef: StructDef): FieldAtomicDef[];
+export declare function getPhysicalFields(structDef: StructDef): FieldDef[];
+export declare function isMeasureLike(field: FieldDef): boolean;
+export declare function isValueString(value: QueryValue, field: FieldDef): value is string | null;
+export declare function isValueNumber(value: QueryValue, field: FieldDef): value is number | null;
+export declare function isValueBoolean(value: QueryValue, field: FieldDef): value is boolean | null;
+export declare function isValueTimestamp(value: QueryValue, field: FieldDef): value is {
+    value: string;
+} | null;
+export declare function isValueDate(value: QueryValue, field: FieldDef): value is {
+    value: string;
+} | null;
+export interface SearchIndexResult {
+    fieldName: string;
+    fieldValue: string;
+    fieldType: string;
+    weight: number;
+}
+export interface SearchValueMapResult {
+    fieldName: string;
+    cardinality: number;
+    values: {
+        fieldValue: string;
+        weight: number;
+    }[];
+}
+export {};