@malloydata/malloy 0.0.334 → 0.0.336

package/dist/api/foundation/core.d.ts

@@ -0,0 +1,493 @@
+import type { LogMessage } from '../../lang';
+import type { BuildID, CompiledQuery, DocumentLocation, BooleanFieldDef, JSONFieldDef, NumberFieldDef, StringFieldDef, FilterCondition, Query as InternalQuery, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQueryDef, StructDef, TurtleDef, NativeUnsupportedFieldDef, ImportLocation, Annotation, AtomicFieldDef, DateFieldDef, ATimestampFieldDef, SourceDef, Argument, SourceComponentInfo, DocumentReference, PersistableSourceDef } from '../../model';
+import { QueryModel } from '../../model';
+import type { Dialect } from '../../dialect';
+import type { BuildGraph, CompileQueryOptions } from './types';
+import type { Tag } from '@malloydata/malloy-tag';
+import type { MalloyTagParse, TagParseSpec } from '../../annotation';
+import type { Taggable } from '../../taggable';
+declare abstract class Entity {
+    private readonly _name;
+    protected readonly _parent?: Explore;
+    private readonly _source?;
+    constructor(name: string, parent?: Explore, source?: Entity);
+    get source(): Entity | undefined;
+    get name(): string;
+    get sourceClasses(): string[];
+    get fieldPath(): string[];
+    hasParentExplore(): this is Field;
+    isExplore(): this is Explore;
+    isQuery(): this is Query;
+    abstract isIntrinsic(): boolean;
+    abstract get location(): DocumentLocation | undefined;
+}
+/**
+ * The relationship of an `Explore` to its source.
+ */
+export declare enum SourceRelationship {
+    /**
+     * The `Explore` is nested data within the source's rows.
+     */
+    Nested = "nested",
+    /**
+     * The `Explore` is the base table.
+     */
+    BaseTable = "base_table",
+    /**
+     * The `Explore` is joined to its source
+     */
+    Cross = "cross",
+    One = "one",
+    Many = "many",
+    Inline = "inline"
+}
+export declare enum AtomicFieldType {
+    String = "string",
+    Number = "number",
+    Boolean = "boolean",
+    Date = "date",
+    Timestamp = "timestamp",
+    Timestamptz = "timestamptz",
+    Json = "json",
+    NativeUnsupported = "sql native",
+    Error = "error"
+}
+export declare enum DateTimeframe {
+    Day = "day",
+    Week = "week",
+    Month = "month",
+    Quarter = "quarter",
+    Year = "year"
+}
+export declare enum TimestampTimeframe {
+    Day = "day",
+    Week = "week",
+    Month = "month",
+    Quarter = "quarter",
+    Year = "year",
+    Second = "second",
+    Hour = "hour",
+    Minute = "minute"
+}
+export declare enum JoinRelationship {
+    OneToOne = "one_to_one",
+    OneToMany = "one_to_many",
+    ManyToOne = "many_to_one"
+}
+export type Field = AtomicField | QueryField | ExploreField;
+export type SerializedExplore = {
+    _structDef: StructDef;
+    sourceExplore?: SerializedExplore;
+    _parentExplore?: SerializedExplore;
+};
+export type SortableField = {
+    field: Field;
+    dir: 'asc' | 'desc' | undefined;
+};
+export type PreparedResultJSON = {
+    query: CompiledQuery;
+    modelDef: ModelDef;
+};
+export declare class Explore extends Entity implements Taggable {
+    protected readonly _structDef: StructDef;
+    protected readonly _parentExplore?: Explore;
+    private _fieldMap;
+    private sourceExplore;
+    private _allFieldsWithOrder;
+    constructor(structDef: StructDef, parentExplore?: Explore, source?: Explore);
+    get source(): Explore | undefined;
+    isIntrinsic(): boolean;
+    isExploreField(): this is ExploreField;
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    getTaglines(prefix?: RegExp): string[];
+    private parsedModelTag?;
+    get modelTag(): Tag;
+    /**
+     * @return The name of the entity.
+     */
+    get name(): string;
+    getQueryByName(name: string): PreparedQuery;
+    private get modelDef();
+    getSingleExploreModel(): Model;
+    private get fieldMap();
+    get allFields(): Field[];
+    get allFieldsWithOrder(): SortableField[];
+    get intrinsicFields(): Field[];
+    get dimensions(): SortableField[];
+    getFieldByName(fieldName: string): Field;
+    getFieldByNameIfExists(fieldName: string): Field | undefined;
+    get primaryKey(): string | undefined;
+    get parentExplore(): Explore | undefined;
+    hasParentExplore(): this is ExploreField;
+    get filters(): FilterCondition[];
+    get limit(): number | undefined;
+    get structDef(): StructDef;
+    get queryTimezone(): string | undefined;
+    get sourceStructDef(): SourceDef | undefined;
+    toJSON(): SerializedExplore;
+    static fromJSON(main_explore: SerializedExplore): Explore;
+    get location(): DocumentLocation | undefined;
+    private collectSourceComponents;
+    /**
+     * THIS IS A HIGHLY EXPERIMENTAL API AND MAY VANISH OR CHANGE WITHOUT NOTICE
+     */
+    getSourceComponents(): SourceComponentInfo[];
+}
+export declare class AtomicField extends Entity implements Taggable {
+    protected fieldTypeDef: AtomicFieldDef;
+    protected parent: Explore;
+    constructor(fieldTypeDef: AtomicFieldDef, parent: Explore, source?: AtomicField);
+    get type(): AtomicFieldType;
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    getTaglines(prefix?: RegExp): string[];
+    isIntrinsic(): boolean;
+    isQueryField(): this is QueryField;
+    isExploreField(): this is ExploreField;
+    isAtomicField(): this is AtomicField;
+    isCalculation(): boolean;
+    get sourceField(): Field;
+    get sourceClasses(): string[];
+    get referenceId(): string | undefined;
+    sourceWasMeasure(): boolean;
+    sourceWasMeasureLike(): boolean;
+    sourceWasDimension(): boolean;
+    hasParentExplore(): this is Field;
+    isString(): this is StringField;
+    isNumber(): this is NumberField;
+    isDate(): this is DateField;
+    isBoolean(): this is BooleanField;
+    isJSON(): this is JSONField;
+    isTimestamp(): this is TimestampField;
+    isUnsupported(): this is UnsupportedField;
+    get parentExplore(): Explore;
+    get expression(): string;
+    get location(): DocumentLocation | undefined;
+}
+export declare class DateField extends AtomicField {
+    private fieldDateDef;
+    constructor(fieldDateDef: DateFieldDef, parent: Explore, source?: AtomicField);
+    get timeframe(): DateTimeframe | undefined;
+}
+export declare class TimestampField extends AtomicField {
+    private fieldTimestampDef;
+    constructor(fieldTimestampDef: ATimestampFieldDef, parent: Explore, source?: AtomicField);
+    get timeframe(): TimestampTimeframe | undefined;
+}
+export declare class NumberField extends AtomicField {
+    private fieldNumberDef;
+    constructor(fieldNumberDef: NumberFieldDef, parent: Explore, source?: AtomicField);
+}
+export declare class BooleanField extends AtomicField {
+    private fieldBooleanDef;
+    constructor(fieldBooleanDef: BooleanFieldDef, parent: Explore, source?: AtomicField);
+}
+export declare class JSONField extends AtomicField {
+    private fieldJSONDef;
+    constructor(fieldJSONDef: JSONFieldDef, parent: Explore, source?: AtomicField);
+}
+export declare class UnsupportedField extends AtomicField {
+    private fieldUnsupportedDef;
+    constructor(fieldUnsupportedDef: NativeUnsupportedFieldDef, parent: Explore, source?: AtomicField);
+    get rawType(): string | undefined;
+}
+export declare class StringField extends AtomicField {
+    private fieldStringDef;
+    constructor(fieldStringDef: StringFieldDef, parent: Explore, source?: AtomicField);
+}
+export declare class Query extends Entity {
+    protected turtleDef: TurtleDef;
+    private sourceQuery?;
+    constructor(turtleDef: TurtleDef, parent?: Explore, source?: Query);
+    get source(): Query | undefined;
+    isIntrinsic(): boolean;
+    get location(): DocumentLocation | undefined;
+}
+export declare class QueryField extends Query implements Taggable {
+    protected parent: Explore;
+    constructor(turtleDef: TurtleDef, parent: Explore, source?: Query);
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    getTaglines(prefix?: RegExp): string[];
+    isQueryField(): this is QueryField;
+    isExploreField(): this is ExploreField;
+    isAtomicField(): this is AtomicField;
+    get sourceClasses(): string[];
+    hasParentExplore(): this is Field;
+    get parentExplore(): Explore;
+    get expression(): string;
+}
+export declare class ExploreField extends Explore {
+    protected _parentExplore: Explore;
+    constructor(structDef: StructDef, parentExplore: Explore, source?: Explore);
+    get joinRelationship(): JoinRelationship;
+    get isRecord(): boolean;
+    get isArray(): boolean;
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    isQueryField(): this is QueryField;
+    isExploreField(): this is ExploreField;
+    isAtomicField(): this is AtomicField;
+    get parentExplore(): Explore;
+    get sourceClasses(): string[];
+    get queryTimezone(): string | undefined;
+}
+export declare class Model implements Taggable {
+    private modelDef;
+    readonly problems: LogMessage[];
+    readonly fromSources: string[];
+    private readonly references;
+    private _queryModel?;
+    constructor(modelDef: ModelDef, problems: LogMessage[], fromSources: string[], existingQueryModel?: QueryModel);
+    get queryModel(): QueryModel;
+    /**
+     * Returns the cached QueryModel if it exists, without creating one.
+     * Used internally to share QueryModel between Model instances when
+     * the model wasn't modified (only queries were added).
+     */
+    getExistingQueryModel(): QueryModel | undefined;
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    getTaglines(prefix?: RegExp): string[];
+    /**
+     * Retrieve a document reference for the token at the given position within
+     * the document that produced this model.
+     *
+     * @param position A position within the document.
+     * @return A `DocumentReference` at that position if one exists.
+     */
+    getReference(position: ModelDocumentPosition): DocumentReference | undefined;
+    /**
+     * Retrieve an import for the token at the given position within
+     * the document that produced this model.
+     *
+     * @param position A position within the document.
+     * @return An `ImportLocation` at that position if one exists.
+     */
+    getImport(position: ModelDocumentPosition): ImportLocation | undefined;
+    /**
+     * Retrieve a prepared query by the name of a query at the top level of the model.
+     *
+     * @param queryName Name of the query to retrieve.
+     * @return A prepared query.
+     */
+    getPreparedQueryByName(queryName: string): PreparedQuery;
+    /**
+     * Retrieve a prepared query by the index of an unnamed query at the top level of a model.
+     *
+     * @param index The index of the query to retrieve.
+     * @return A prepared query.
+     */
+    getPreparedQueryByIndex(index: number): PreparedQuery;
+    /**
+     * Retrieve a prepared query for the final unnamed query at the top level of a model.
+     *
+     * @return A prepared query.
+     */
+    get preparedQuery(): PreparedQuery;
+    /**
+     * Retrieve a prepared query for the final unnamed query at the top level of a model.
+     *
+     * @return A prepared query.
+     */
+    getPreparedQuery(): PreparedQuery;
+    /**
+     * Retrieve an `Explore` from the model by name.
+     *
+     * @param name The name of the `Explore` to retrieve.
+     * @return An `Explore`.
+     */
+    getExploreByName(name: string): Explore;
+    /**
+     * Get an array of `Explore`s contained in the model.
+     *
+     * @return An array of `Explore`s contained in the model.
+     */
+    get explores(): Explore[];
+    /**
+     * Get an array of `NamedQueryDef`s contained in the model.
+     *
+     * @return An array of `NamedQueryDef`s contained in the model.
+     */
+    get namedQueries(): NamedQueryDef[];
+    get exportedExplores(): Explore[];
+    get _modelDef(): ModelDef;
+    /**
+     * Get the build plan for all #@ persist sources.
+     *
+     * Walks through ALL queries and sources in the model, finding any persistent
+     * dependencies they reference (including hidden dependencies from imports).
+     *
+     * Returns a BuildPlan containing:
+     * - `graphs`: Build graphs for root sources only (minimal build set)
+     * - `sources`: Map from sourceId to PersistSource (all persist sources)
+     *
+     * The minimal build set contains only "root" sources - those not depended
+     * on by any other persist source. Each root includes its transitive
+     * dependencies in the dependsOn field, preserving the tree structure
+     * for parallel building.
+     *
+     * @return BuildPlan with graphs and sources map
+     */
+    getBuildPlan(): BuildPlan;
+}
+/**
+ * The complete build plan for persistent sources in a model.
+ *
+ * Returned by `Model.getBuildPlan()`. Contains:
+ * - `graphs`: Dependency-ordered build graphs grouped by connection
+ * - `sources`: Map from sourceId to PersistSource for accessing source details
+ */
+export interface BuildPlan {
+    /** Build graphs grouped by connection, with leveled nodes for parallel execution */
+    graphs: BuildGraph[];
+    /** Map from sourceId to PersistSource for accessing source details */
+    sources: Record<string, PersistSource>;
+}
+/**
+ * A wrapper around a source that has #@ persist annotation.
+ *
+ * Only sources backed by queries can be persisted:
+ * - `query_source`: `source: x is y -> {...}`
+ * - `sql_select`: `source: x is conn.sql("...")`
+ *
+ * Provides access to source identity, SQL generation, and metadata needed
+ * for building and caching source results.
+ */
+export declare class PersistSource implements Taggable {
+    private readonly explore;
+    private readonly model;
+    private readonly persistableDef;
+    constructor(explore: Explore, model: Model);
+    /**
+     * The name of this source.
+     */
+    get name(): string;
+    /**
+     * The stable identity of this source: "sourceName@modelURL".
+     * Used as lookup key during compilation and in build graphs.
+     */
+    get sourceID(): string;
+    /**
+     * The underlying Explore.
+     */
+    get _explore(): Explore;
+    /**
+     * The annotation on this source.
+     */
+    get annotation(): Annotation | undefined;
+    /**
+     * Parse the source's tags.
+     */
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /**
+     * Get annotation taglines matching an optional prefix.
+     */
+    getTaglines(prefix?: RegExp): string[];
+    /**
+     * The connection name for this source.
+     */
+    get connectionName(): string;
+    /**
+     * The dialect name for this source.
+     */
+    get dialectName(): string;
+    /**
+     * The dialect for this source.
+     */
+    get dialect(): Dialect;
+    /**
+     * Compute the BuildID for this source.
+     *
+     * BuildID is a hash of the connection config and SQL content.
+     * Different connection configs or SQL changes produce different BuildIDs.
+     *
+     * @param connectionDigest - Digest from connection.getDigest()
+     * @param sql - The SQL for this source (from getSQL())
+     * @return The BuildID for manifest lookup
+     */
+    makeBuildId(connectionDigest: string, sql: string): BuildID;
+    /**
+     * Get the SQL for this persist source.
+     *
+     * For sql_select sources, returns the SQL string (with segment expansion).
+     * For query_source sources, compiles the inner query to SQL.
+     *
+     * @param options - Compile options including buildManifest for persistence.
+     * @return The SQL string for this source.
+     */
+    getSQL(options?: CompileQueryOptions): string;
+    /**
+     * Get the underlying persistable source definition.
+     */
+    get _sourceDef(): PersistableSourceDef;
+    /**
+     * Get the Model this source belongs to.
+     */
+    get _model(): Model;
+}
+export declare class PreparedQuery implements Taggable {
+    private _model;
+    problems: LogMessage[];
+    name?: string | undefined;
+    _query: InternalQuery | NamedQueryDef;
+    constructor(query: InternalQuery, _model: Model, problems: LogMessage[], name?: string | undefined);
+    get _modelDef(): ModelDef;
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    getTaglines(prefix?: RegExp): string[];
+    /**
+     * Generate the SQL for this query.
+     *
+     * @return A fully-prepared query (which contains the generated SQL).
+     */
+    get preparedResult(): PreparedResult;
+    /**
+     * Generate the SQL for this query.
+     *
+     * @return A fully-prepared query (which contains the generated SQL).
+     * @param options.eventStream An event stream to use when compiling the SQL
+     */
+    getPreparedResult(options?: CompileQueryOptions): PreparedResult;
+    get dialect(): string;
+    /**
+     * Get the flattened version of a query -- one that does not have a `pipeHead`.
+     * @deprecated Because queries can no longer have `pipeHead`s.
+     */
+    getFlattenedQuery(_defaultName: string): PreparedQuery;
+    /**
+     * Get the Model this query belongs to.
+     */
+    get model(): Model;
+}
+export declare class PreparedResult implements Taggable {
+    protected modelDef: ModelDef;
+    protected inner: CompiledQuery;
+    constructor(query: CompiledQuery, modelDef: ModelDef);
+    static fromJson({ query, modelDef, }: PreparedResultJSON): PreparedResult;
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    getTaglines(prefix?: RegExp): string[];
+    get annotation(): Annotation | undefined;
+    get modelAnnotation(): Annotation | undefined;
+    get modelTag(): Tag;
+    /**
+     * @return The name of the connection this query should be run against.
+     */
+    get connectionName(): string;
+    get _rawQuery(): CompiledQuery;
+    get _modelDef(): ModelDef;
+    /**
+     * @return The SQL that should be run against the SQL runner
+     * with the connection name `this.getConnectionName()`.
+     */
+    get sql(): string;
+    /**
+     * @return The `Explore` representing the data that will be returned by running this query.
+     */
+    get resultExplore(): Explore;
+    get sourceExplore(): Explore | undefined;
+    get _sourceExploreName(): string;
+    get _sourceArguments(): Record<string, Argument> | undefined;
+    get _sourceFilters(): FilterCondition[];
+    /**
+     * @return Whether this result has a schema. DDL statements (INSTALL, LOAD,
+     * CREATE SECRET, etc.) do not return a schema.
+     */
+    get hasSchema(): boolean;
+}
+export {};