@malloydata/malloy 0.0.335 → 0.0.337

package/dist/api/foundation/core.js

@@ -0,0 +1,1247 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreparedResult = exports.PreparedQuery = exports.PersistSource = exports.Model = exports.ExploreField = exports.QueryField = exports.Query = exports.StringField = exports.UnsupportedField = exports.JSONField = exports.BooleanField = exports.NumberField = exports.TimestampField = exports.DateField = exports.AtomicField = exports.Explore = exports.JoinRelationship = exports.TimestampTimeframe = exports.DateTimeframe = exports.AtomicFieldType = exports.SourceRelationship = void 0;
+const model_1 = require("../../model");
+const utils_1 = require("../../model/utils");
+const dialect_1 = require("../../dialect");
+const persist_utils_1 = require("../../model/persist_utils");
+const source_def_utils_1 = require("../../model/source_def_utils");
+const annotation_1 = require("../../annotation");
+const utils_2 = require("../../lang/utils");
+const reference_list_1 = require("../../lang/reference-list");
+function isSourceComponent(source) {
+    return (source.type === 'table' ||
+        source.type === 'sql_select' ||
+        source.type === 'query_source');
+}
+// =============================================================================
+// Entity - Base class for Explore and Field types
+// =============================================================================
+class Entity {
+    constructor(name, parent, source) {
+        this._name = name;
+        this._parent = parent;
+        this._source = source;
+    }
+    get source() {
+        return this._source;
+    }
+    get name() {
+        return this._name;
+    }
+    get sourceClasses() {
+        const sourceClasses = [];
+        if (this.source) {
+            sourceClasses.push(this.source.name);
+        }
+        sourceClasses.push(this.name);
+        return sourceClasses;
+    }
+    get fieldPath() {
+        const path = [this.name];
+        let f = this._parent;
+        while (f) {
+            path.unshift(f.name);
+            f = f._parent;
+        }
+        return path;
+    }
+    hasParentExplore() {
+        return this._parent !== undefined;
+    }
+    isExplore() {
+        return this instanceof Explore;
+    }
+    isQuery() {
+        return this instanceof QueryField;
+    }
+}
+// =============================================================================
+// Enums
+// =============================================================================
+/**
+ * The relationship of an `Explore` to its source.
+ */
+var SourceRelationship;
+(function (SourceRelationship) {
+    /**
+     * The `Explore` is nested data within the source's rows.
+     */
+    SourceRelationship["Nested"] = "nested";
+    /**
+     * The `Explore` is the base table.
+     */
+    SourceRelationship["BaseTable"] = "base_table";
+    /**
+     * The `Explore` is joined to its source
+     */
+    SourceRelationship["Cross"] = "cross";
+    SourceRelationship["One"] = "one";
+    SourceRelationship["Many"] = "many";
+    // TODO document this
+    SourceRelationship["Inline"] = "inline";
+})(SourceRelationship || (exports.SourceRelationship = SourceRelationship = {}));
+var AtomicFieldType;
+(function (AtomicFieldType) {
+    AtomicFieldType["String"] = "string";
+    AtomicFieldType["Number"] = "number";
+    AtomicFieldType["Boolean"] = "boolean";
+    AtomicFieldType["Date"] = "date";
+    AtomicFieldType["Timestamp"] = "timestamp";
+    AtomicFieldType["Timestamptz"] = "timestamptz";
+    AtomicFieldType["Json"] = "json";
+    AtomicFieldType["NativeUnsupported"] = "sql native";
+    AtomicFieldType["Error"] = "error";
+})(AtomicFieldType || (exports.AtomicFieldType = AtomicFieldType = {}));
+var DateTimeframe;
+(function (DateTimeframe) {
+    DateTimeframe["Day"] = "day";
+    DateTimeframe["Week"] = "week";
+    DateTimeframe["Month"] = "month";
+    DateTimeframe["Quarter"] = "quarter";
+    DateTimeframe["Year"] = "year";
+})(DateTimeframe || (exports.DateTimeframe = DateTimeframe = {}));
+var TimestampTimeframe;
+(function (TimestampTimeframe) {
+    TimestampTimeframe["Day"] = "day";
+    TimestampTimeframe["Week"] = "week";
+    TimestampTimeframe["Month"] = "month";
+    TimestampTimeframe["Quarter"] = "quarter";
+    TimestampTimeframe["Year"] = "year";
+    TimestampTimeframe["Second"] = "second";
+    TimestampTimeframe["Hour"] = "hour";
+    TimestampTimeframe["Minute"] = "minute";
+})(TimestampTimeframe || (exports.TimestampTimeframe = TimestampTimeframe = {}));
+var JoinRelationship;
+(function (JoinRelationship) {
+    JoinRelationship["OneToOne"] = "one_to_one";
+    JoinRelationship["OneToMany"] = "one_to_many";
+    JoinRelationship["ManyToOne"] = "many_to_one";
+})(JoinRelationship || (exports.JoinRelationship = JoinRelationship = {}));
+// =============================================================================
+// Explore
+// =============================================================================
+class Explore extends Entity {
+    constructor(structDef, parentExplore, source) {
+        super(structDef.as || structDef.name, parentExplore, source);
+        this._structDef = structDef;
+        this._parentExplore = parentExplore;
+        this.sourceExplore = source;
+    }
+    get source() {
+        return this.sourceExplore;
+    }
+    isIntrinsic() {
+        if ((0, model_1.isAtomicFieldType)(this._structDef.type)) {
+            return !('e' in this._structDef);
+        }
+        return false;
+    }
+    isExploreField() {
+        return false;
+    }
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this._structDef.annotation, spec);
+    }
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this._structDef.annotation, prefix);
+    }
+    get modelTag() {
+        this.parsedModelTag || (this.parsedModelTag = (0, annotation_1.annotationToTag)(this._structDef.modelAnnotation).tag);
+        return this.parsedModelTag;
+    }
+    /**
+     * @return The name of the entity.
+     */
+    get name() {
+        return this.structDef.as || this.structDef.name;
+    }
+    getQueryByName(name) {
+        const structRef = this.sourceStructDef;
+        if (!structRef) {
+            throw new Error(`Cannot get query by name from a struct of type ${this.structDef.type}`);
+        }
+        const view = structRef.fields.find(f => { var _a; return ((_a = f.as) !== null && _a !== void 0 ? _a : f.name) === name; });
+        if (view === undefined) {
+            throw new Error(`No such view named \`${name}\``);
+        }
+        if (view.type !== 'turtle') {
+            throw new Error(`\`${name}\` is not a view`);
+        }
+        const internalQuery = {
+            type: 'query',
+            structRef,
+            pipeline: view.pipeline,
+        };
+        return new PreparedQuery(internalQuery, this.getSingleExploreModel(), [], name);
+    }
+    get modelDef() {
+        if (!(0, model_1.isSourceDef)(this.structDef)) {
+            throw new Error(`Cannot create pseudo model for struct type ${this.structDef.type}`);
+        }
+        const def = (0, utils_1.mkModelDef)('generated_model');
+        def.contents[this.structDef.name] = this.structDef;
+        return def;
+    }
+    getSingleExploreModel() {
+        return new Model(this.modelDef, [], []);
+    }
+    get fieldMap() {
+        var _a;
+        if (this._fieldMap === undefined) {
+            const sourceFields = ((_a = this.source) === null || _a === void 0 ? void 0 : _a.fieldMap) || new Map();
+            this._fieldMap = new Map(this.structDef.fields.map(fieldDef => {
+                const name = fieldDef.as || fieldDef.name;
+                const sourceField = sourceFields.get(fieldDef.name);
+                if ((0, model_1.isJoined)(fieldDef)) {
+                    return [name, new ExploreField(fieldDef, this, sourceField)];
+                }
+                else if (fieldDef.type === 'turtle') {
+                    return [name, new QueryField(fieldDef, this, sourceField)];
+                }
+                else {
+                    if (fieldDef.type === 'string') {
+                        return [name, new StringField(fieldDef, this, sourceField)];
+                    }
+                    else if (fieldDef.type === 'number') {
+                        return [name, new NumberField(fieldDef, this, sourceField)];
+                    }
+                    else if (fieldDef.type === 'date') {
+                        // TODO this is a hack
+                        if (fieldDef.timeframe &&
+                            ['day_of_month', 'day_of_week', 'day_of_year'].includes(fieldDef.timeframe)) {
+                            return [
+                                name,
+                                new NumberField({ ...fieldDef, type: 'number' }, this, sourceField),
+                            ];
+                        }
+                        return [name, new DateField(fieldDef, this, sourceField)];
+                    }
+                    else if (fieldDef.type === 'timestamp') {
+                        return [name, new TimestampField(fieldDef, this, sourceField)];
+                    }
+                    else if (fieldDef.type === 'timestamptz') {
+                        return [name, new TimestampField(fieldDef, this, sourceField)];
+                    }
+                    else if (fieldDef.type === 'boolean') {
+                        return [name, new BooleanField(fieldDef, this, sourceField)];
+                    }
+                    else if (fieldDef.type === 'json') {
+                        return [name, new JSONField(fieldDef, this, sourceField)];
+                    }
+                    else if (fieldDef.type === 'sql native') {
+                        return [name, new UnsupportedField(fieldDef, this, sourceField)];
+                    }
+                }
+            }));
+        }
+        return this._fieldMap;
+    }
+    get allFields() {
+        return [...this.fieldMap.values()];
+    }
+    get allFieldsWithOrder() {
+        var _a, _b, _c;
+        if (!this._allFieldsWithOrder) {
+            const orderByFields = [
+                ...(((_c = (_b = (_a = this.sourceStructDef) === null || _a === void 0 ? void 0 : _a.resultMetadata) === null || _b === void 0 ? void 0 : _b.orderBy) === null || _c === void 0 ? void 0 : _c.map(f => {
+                    if (typeof f.field === 'string') {
+                        const a = {
+                            field: this.fieldMap.get(f.field),
+                            dir: f.dir,
+                        };
+                        return a;
+                    }
+                    throw new Error('Does not support mapping order by from number.');
+                })) || []),
+            ];
+            const orderByFieldSet = new Set(orderByFields.map(f => f.field.name));
+            this._allFieldsWithOrder = [
+                ...orderByFields,
+                ...this.allFields
+                    .filter(f => !orderByFieldSet.has(f.name))
+                    .map(field => {
+                    return {
+                        field,
+                        dir: 'asc',
+                    };
+                }),
+            ];
+        }
+        return this._allFieldsWithOrder;
+    }
+    get intrinsicFields() {
+        return [...this.fieldMap.values()].filter(f => f.isIntrinsic());
+    }
+    get dimensions() {
+        return [...this.allFieldsWithOrder].filter(f => f.field.isAtomicField() && f.field.sourceWasDimension());
+    }
+    getFieldByName(fieldName) {
+        const field = this.fieldMap.get(fieldName);
+        if (field === undefined) {
+            throw new Error(`No such field ${fieldName}.`);
+        }
+        return field;
+    }
+    getFieldByNameIfExists(fieldName) {
+        return this.fieldMap.get(fieldName);
+    }
+    get primaryKey() {
+        var _a;
+        return (_a = this.sourceStructDef) === null || _a === void 0 ? void 0 : _a.primaryKey;
+    }
+    get parentExplore() {
+        return this._parentExplore;
+    }
+    hasParentExplore() {
+        return this instanceof ExploreField;
+    }
+    get filters() {
+        var _a;
+        if ((0, model_1.isSourceDef)(this.structDef)) {
+            return ((_a = this.structDef.resultMetadata) === null || _a === void 0 ? void 0 : _a.filterList) || [];
+        }
+        return [];
+    }
+    get limit() {
+        var _a, _b;
+        return (_b = (_a = this.sourceStructDef) === null || _a === void 0 ? void 0 : _a.resultMetadata) === null || _b === void 0 ? void 0 : _b.limit;
+    }
+    get structDef() {
+        return this._structDef;
+    }
+    get queryTimezone() {
+        var _a;
+        return (_a = this.sourceStructDef) === null || _a === void 0 ? void 0 : _a.queryTimezone;
+    }
+    get sourceStructDef() {
+        if ((0, model_1.isSourceDef)(this.structDef)) {
+            return this.structDef;
+        }
+    }
+    toJSON() {
+        var _a, _b;
+        return {
+            _structDef: this._structDef,
+            sourceExplore: (_a = this.sourceExplore) === null || _a === void 0 ? void 0 : _a.toJSON(),
+            _parentExplore: (_b = this._parentExplore) === null || _b === void 0 ? void 0 : _b.toJSON(),
+        };
+    }
+    static fromJSON(main_explore) {
+        const parentExplore = main_explore._parentExplore !== undefined
+            ? Explore.fromJSON(main_explore._parentExplore)
+            : undefined;
+        const sourceExplore = main_explore.sourceExplore !== undefined
+            ? Explore.fromJSON(main_explore.sourceExplore)
+            : undefined;
+        return new Explore(main_explore._structDef, parentExplore, sourceExplore);
+    }
+    get location() {
+        return this.structDef.location;
+    }
+    collectSourceComponents(structDef) {
+        const sources = [];
+        if (structDef.type === 'composite') {
+            for (const source of structDef.sources) {
+                sources.push(...this.collectSourceComponents(source));
+            }
+            return sources;
+        }
+        if (isSourceComponent(structDef)) {
+            if (structDef.type === 'table') {
+                sources.push({
+                    type: 'table',
+                    tableName: structDef.tablePath,
+                    componentID: `${structDef.connection}:${structDef.tablePath}`,
+                    sourceID: `${structDef.connection}:${structDef.tablePath}`,
+                });
+            }
+            else if (structDef.type === 'sql_select') {
+                sources.push({
+                    type: 'sql',
+                    selectStatement: structDef.selectStr,
+                    componentID: `${structDef.connection}:${structDef.selectStr}`,
+                    sourceID: `${structDef.connection}:${structDef.selectStr}`,
+                });
+            }
+            else if (structDef.type === 'query_source') {
+                let sql;
+                try {
+                    const preparedQuery = new PreparedQuery(structDef.query, this.getSingleExploreModel(), []);
+                    const preparedResult = preparedQuery.getPreparedResult();
+                    sql = preparedResult.sql;
+                }
+                catch (error) {
+                    sql = `-- Could not compile SQL for query ${structDef.query.name || 'unnamed query'}: ${error instanceof Error ? error.message : String(error)}`;
+                }
+                const componentID = `${structDef.connection}:${sql}`;
+                sources.push({
+                    type: 'sql',
+                    selectStatement: sql,
+                    componentID: componentID,
+                    sourceID: componentID,
+                });
+            }
+        }
+        else {
+            return [];
+        }
+        for (const field of structDef.fields) {
+            if ((0, model_1.isJoined)(field)) {
+                sources.push(...this.collectSourceComponents(field));
+            }
+        }
+        return sources;
+    }
+    /**
+     * THIS IS A HIGHLY EXPERIMENTAL API AND MAY VANISH OR CHANGE WITHOUT NOTICE
+     */
+    getSourceComponents() {
+        const uniqueSources = {};
+        if ((0, model_1.isSourceDef)(this.structDef)) {
+            const allSources = this.collectSourceComponents(this.structDef);
+            for (const source of allSources) {
+                if (source.componentID) {
+                    uniqueSources[source.componentID] = source;
+                }
+                else if (source.sourceID) {
+                    uniqueSources[source.sourceID] = source;
+                }
+            }
+        }
+        return Object.values(uniqueSources);
+    }
+}
+exports.Explore = Explore;
+// =============================================================================
+// AtomicField and subclasses
+// =============================================================================
+class AtomicField extends Entity {
+    constructor(fieldTypeDef, parent, source) {
+        super(fieldTypeDef.as || fieldTypeDef.name, parent, source);
+        this.fieldTypeDef = fieldTypeDef;
+        this.parent = parent;
+    }
+    get type() {
+        switch (this.fieldTypeDef.type) {
+            case 'string':
+                return AtomicFieldType.String;
+            case 'boolean':
+                return AtomicFieldType.Boolean;
+            case 'date':
+                return AtomicFieldType.Date;
+            case 'timestamp':
+                return AtomicFieldType.Timestamp;
+            case 'timestamptz':
+                return AtomicFieldType.Timestamptz;
+            case 'number':
+                return AtomicFieldType.Number;
+            case 'json':
+                return AtomicFieldType.Json;
+            case 'sql native':
+                return AtomicFieldType.NativeUnsupported;
+            case 'error':
+                return AtomicFieldType.Error;
+            case 'record':
+            case 'array':
+                throw new Error(`MTOY TODO IMPLEMENT Atomic ${this.fieldTypeDef.type}`);
+            default: {
+                const x = this.fieldTypeDef;
+                throw new Error(`Can't make an atomic field from ${x}`);
+            }
+        }
+    }
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this.fieldTypeDef.annotation, spec);
+    }
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this.fieldTypeDef.annotation, prefix);
+    }
+    isIntrinsic() {
+        return (0, model_1.fieldIsIntrinsic)(this.fieldTypeDef);
+    }
+    isQueryField() {
+        return false;
+    }
+    isExploreField() {
+        return false;
+    }
+    isAtomicField() {
+        return true;
+    }
+    isCalculation() {
+        return (0, model_1.expressionIsCalculation)(this.fieldTypeDef.expressionType);
+    }
+    get sourceField() {
+        throw new Error();
+    }
+    get sourceClasses() {
+        const sourceField = this.fieldTypeDef.name || this.fieldTypeDef.as;
+        return sourceField ? [sourceField] : [];
+    }
+    get referenceId() {
+        var _a;
+        return (_a = this.fieldTypeDef.resultMetadata) === null || _a === void 0 ? void 0 : _a.referenceId;
+    }
+    sourceWasMeasure() {
+        var _a;
+        return ((_a = this.fieldTypeDef.resultMetadata) === null || _a === void 0 ? void 0 : _a.fieldKind) === 'measure';
+    }
+    sourceWasMeasureLike() {
+        var _a, _b;
+        return (((_a = this.fieldTypeDef.resultMetadata) === null || _a === void 0 ? void 0 : _a.fieldKind) === 'measure' ||
+            ((_b = this.fieldTypeDef.resultMetadata) === null || _b === void 0 ? void 0 : _b.fieldKind) === 'struct');
+    }
+    sourceWasDimension() {
+        var _a;
+        return ((_a = this.fieldTypeDef.resultMetadata) === null || _a === void 0 ? void 0 : _a.fieldKind) === 'dimension';
+    }
+    hasParentExplore() {
+        return true;
+    }
+    isString() {
+        return this instanceof StringField;
+    }
+    isNumber() {
+        return this instanceof NumberField;
+    }
+    isDate() {
+        return this instanceof DateField;
+    }
+    isBoolean() {
+        return this instanceof BooleanField;
+    }
+    isJSON() {
+        return this instanceof JSONField;
+    }
+    isTimestamp() {
+        return this instanceof TimestampField;
+    }
+    isUnsupported() {
+        return this instanceof UnsupportedField;
+    }
+    get parentExplore() {
+        return this.parent;
+    }
+    get expression() {
+        const dot = '.';
+        const resultMetadata = this.fieldTypeDef.resultMetadata;
+        return ((resultMetadata === null || resultMetadata === void 0 ? void 0 : resultMetadata.sourceExpression) ||
+            ((resultMetadata === null || resultMetadata === void 0 ? void 0 : resultMetadata.sourceField.includes(dot))
+                ? resultMetadata === null || resultMetadata === void 0 ? void 0 : resultMetadata.sourceField
+                : this.name));
+    }
+    get location() {
+        return this.fieldTypeDef.location;
+    }
+}
+exports.AtomicField = AtomicField;
+class DateField extends AtomicField {
+    constructor(fieldDateDef, parent, source) {
+        super(fieldDateDef, parent, source);
+        this.fieldDateDef = fieldDateDef;
+    }
+    get timeframe() {
+        if (this.fieldDateDef.timeframe === undefined) {
+            return undefined;
+        }
+        switch (this.fieldDateDef.timeframe) {
+            case 'day':
+                return DateTimeframe.Day;
+            case 'week':
+                return DateTimeframe.Week;
+            case 'month':
+                return DateTimeframe.Month;
+            case 'quarter':
+                return DateTimeframe.Quarter;
+            case 'year':
+                return DateTimeframe.Year;
+        }
+    }
+}
+exports.DateField = DateField;
+class TimestampField extends AtomicField {
+    constructor(fieldTimestampDef, parent, source) {
+        super(fieldTimestampDef, parent, source);
+        this.fieldTimestampDef = fieldTimestampDef;
+    }
+    get timeframe() {
+        if (this.fieldTimestampDef.timeframe === undefined) {
+            return undefined;
+        }
+        switch (this.fieldTimestampDef.timeframe) {
+            case 'day':
+                return TimestampTimeframe.Day;
+            case 'week':
+                return TimestampTimeframe.Week;
+            case 'month':
+                return TimestampTimeframe.Month;
+            case 'quarter':
+                return TimestampTimeframe.Quarter;
+            case 'year':
+                return TimestampTimeframe.Year;
+            case 'second':
+                return TimestampTimeframe.Second;
+            case 'hour':
+                return TimestampTimeframe.Hour;
+            case 'minute':
+                return TimestampTimeframe.Minute;
+        }
+    }
+}
+exports.TimestampField = TimestampField;
+class NumberField extends AtomicField {
+    constructor(fieldNumberDef, parent, source) {
+        super(fieldNumberDef, parent, source);
+        this.fieldNumberDef = fieldNumberDef;
+    }
+}
+exports.NumberField = NumberField;
+class BooleanField extends AtomicField {
+    constructor(fieldBooleanDef, parent, source) {
+        super(fieldBooleanDef, parent, source);
+        this.fieldBooleanDef = fieldBooleanDef;
+    }
+}
+exports.BooleanField = BooleanField;
+class JSONField extends AtomicField {
+    constructor(fieldJSONDef, parent, source) {
+        super(fieldJSONDef, parent, source);
+        this.fieldJSONDef = fieldJSONDef;
+    }
+}
+exports.JSONField = JSONField;
+class UnsupportedField extends AtomicField {
+    constructor(fieldUnsupportedDef, parent, source) {
+        super(fieldUnsupportedDef, parent, source);
+        this.fieldUnsupportedDef = fieldUnsupportedDef;
+    }
+    get rawType() {
+        return this.fieldUnsupportedDef.rawType;
+    }
+}
+exports.UnsupportedField = UnsupportedField;
+class StringField extends AtomicField {
+    constructor(fieldStringDef, parent, source) {
+        super(fieldStringDef, parent, source);
+        this.fieldStringDef = fieldStringDef;
+    }
+}
+exports.StringField = StringField;
+// =============================================================================
+// Query and QueryField
+// =============================================================================
+class Query extends Entity {
+    constructor(turtleDef, parent, source) {
+        super(turtleDef.as || turtleDef.name, parent, source);
+        this.turtleDef = turtleDef;
+    }
+    get source() {
+        return this.sourceQuery;
+    }
+    isIntrinsic() {
+        return false;
+    }
+    get location() {
+        return this.turtleDef.location;
+    }
+}
+exports.Query = Query;
+class QueryField extends Query {
+    constructor(turtleDef, parent, source) {
+        super(turtleDef, parent, source);
+        this.parent = parent;
+    }
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this.turtleDef.annotation, spec);
+    }
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this.turtleDef.annotation, prefix);
+    }
+    isQueryField() {
+        return true;
+    }
+    isExploreField() {
+        return false;
+    }
+    isAtomicField() {
+        return false;
+    }
+    get sourceClasses() {
+        const sourceField = this.turtleDef.name || this.turtleDef.as;
+        return sourceField ? [sourceField] : [];
+    }
+    hasParentExplore() {
+        return true;
+    }
+    get parentExplore() {
+        return this.parent;
+    }
+    get expression() {
+        return this.name;
+    }
+}
+exports.QueryField = QueryField;
+// =============================================================================
+// ExploreField
+// =============================================================================
+class ExploreField extends Explore {
+    constructor(structDef, parentExplore, source) {
+        super(structDef, parentExplore, source);
+        this._parentExplore = parentExplore;
+    }
+    get joinRelationship() {
+        if ((0, model_1.isJoined)(this.structDef)) {
+            switch (this.structDef.join) {
+                case 'one':
+                    return JoinRelationship.OneToOne;
+                case 'many':
+                case 'cross':
+                    return JoinRelationship.ManyToOne;
+            }
+        }
+        throw new Error('A source field must have a join relationship.');
+    }
+    get isRecord() {
+        return this.joinRelationship === JoinRelationship.OneToOne;
+    }
+    get isArray() {
+        return this.joinRelationship !== JoinRelationship.OneToOne;
+    }
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this._structDef.annotation, spec);
+    }
+    isQueryField() {
+        return false;
+    }
+    isExploreField() {
+        return true;
+    }
+    isAtomicField() {
+        return false;
+    }
+    get parentExplore() {
+        return this._parentExplore;
+    }
+    get sourceClasses() {
+        const sourceField = this.structDef.name || this.structDef.as;
+        return sourceField ? [sourceField] : [];
+    }
+    get queryTimezone() {
+        if ((0, model_1.isRecordOrRepeatedRecord)(this._structDef)) {
+            return this._structDef.queryTimezone;
+        }
+        return super.queryTimezone;
+    }
+}
+exports.ExploreField = ExploreField;
+// =============================================================================
+// Model
+// =============================================================================
+class Model {
+    constructor(modelDef, problems, fromSources, existingQueryModel) {
+        var _a, _b;
+        this.modelDef = modelDef;
+        this.problems = problems;
+        this.fromSources = fromSources;
+        this.references = new reference_list_1.ReferenceList((_a = fromSources[0]) !== null && _a !== void 0 ? _a : '', (_b = modelDef.references) !== null && _b !== void 0 ? _b : []);
+        this._queryModel = existingQueryModel;
+    }
+    get queryModel() {
+        if (!this._queryModel) {
+            this._queryModel = new model_1.QueryModel(this.modelDef);
+        }
+        return this._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() {
+        return this._queryModel;
+    }
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this.modelDef.annotation, spec);
+    }
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this.modelDef.annotation, prefix);
+    }
+    /**
+     * 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) {
+        return this.references.find(position);
+    }
+    /**
+     * 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) {
+        var _a;
+        return (_a = this.modelDef.imports) === null || _a === void 0 ? void 0 : _a.find(i => (0, utils_2.locationContainsPosition)(i.location, position));
+    }
+    /**
+     * 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) {
+        const query = this.modelDef.contents[queryName];
+        if ((query === null || query === void 0 ? void 0 : query.type) === 'query') {
+            return new PreparedQuery(query, this, this.problems, queryName);
+        }
+        throw new Error('Given query name does not refer to a named query.');
+    }
+    /**
+     * 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) {
+        if (index < 0) {
+            throw new Error(`Invalid index ${index}.`);
+        }
+        else if (index >= this.modelDef.queryList.length) {
+            throw new Error(`Query index ${index} is out of bounds.`);
+        }
+        return new PreparedQuery(this.modelDef.queryList[index], this, this.problems);
+    }
+    /**
+     * Retrieve a prepared query for the final unnamed query at the top level of a model.
+     *
+     * @return A prepared query.
+     */
+    get preparedQuery() {
+        return this.getPreparedQuery();
+    }
+    /**
+     * Retrieve a prepared query for the final unnamed query at the top level of a model.
+     *
+     * @return A prepared query.
+     */
+    getPreparedQuery() {
+        if (this.modelDef.queryList.length === 0) {
+            throw new Error('Model has no queries.');
+        }
+        return new PreparedQuery(this.modelDef.queryList[this.modelDef.queryList.length - 1], this, this.problems);
+    }
+    /**
+     * Retrieve an `Explore` from the model by name.
+     *
+     * @param name The name of the `Explore` to retrieve.
+     * @return An `Explore`.
+     */
+    getExploreByName(name) {
+        const struct = this.modelDef.contents[name];
+        if (struct && (0, model_1.isSourceDef)(struct)) {
+            return new Explore(struct);
+        }
+        throw new Error("'name' is not an explore");
+    }
+    /**
+     * Get an array of `Explore`s contained in the model.
+     *
+     * @return An array of `Explore`s contained in the model.
+     */
+    get explores() {
+        return Object.values(this.modelDef.contents)
+            .filter(model_1.isSourceDef)
+            .map(structDef => new Explore(structDef));
+    }
+    /**
+     * Get an array of `NamedQueryDef`s contained in the model.
+     *
+     * @return An array of `NamedQueryDef`s contained in the model.
+     */
+    get namedQueries() {
+        const isNamedQueryDef = (object) => object.type === 'query';
+        return Object.values(this.modelDef.contents).filter(isNamedQueryDef);
+    }
+    get exportedExplores() {
+        return this.explores.filter(explore => this.modelDef.exports.includes(explore.name));
+    }
+    get _modelDef() {
+        return this.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() {
+        // Require experimental.persistence compiler flag
+        const modelTag = this.tagParse({ prefix: /^##! / }).tag;
+        if (!modelTag.has('experimental', 'persistence')) {
+            throw new Error('Model must have ##! experimental.persistence to use getBuildPlan()');
+        }
+        const allDeps = [];
+        // Walk all objects in the model to find persistent dependencies
+        for (const obj of Object.values(this.modelDef.contents)) {
+            if (obj.type === 'query' || (0, model_1.isSourceDef)(obj)) {
+                allDeps.push(...(0, persist_utils_1.findPersistentDependencies)(obj, this.modelDef));
+            }
+        }
+        // Also walk queryList (unnamed queries)
+        for (const query of this.modelDef.queryList) {
+            allDeps.push(...(0, persist_utils_1.findPersistentDependencies)(query, this.modelDef));
+        }
+        if (allDeps.length === 0) {
+            return { graphs: [], sources: {} };
+        }
+        // Find the minimal set of root graphs
+        const rootNodes = (0, persist_utils_1.minimalBuildGraph)(allDeps);
+        // Build the sources map from all persistent sourceIDs encountered
+        const sourcesMap = {};
+        const collectSources = (nodes) => {
+            for (const node of nodes) {
+                if (!(node.sourceID in sourcesMap)) {
+                    const sourceDef = (0, source_def_utils_1.resolveSourceID)(this.modelDef, node.sourceID);
+                    if (sourceDef) {
+                        sourcesMap[node.sourceID] = new PersistSource(new Explore(sourceDef), this);
+                    }
+                }
+                collectSources(node.dependsOn);
+            }
+        };
+        collectSources(rootNodes);
+        // Group root nodes by connection
+        const graphsByConnection = new Map();
+        for (const node of rootNodes) {
+            const persistSource = sourcesMap[node.sourceID];
+            if (!persistSource)
+                continue;
+            const connName = persistSource.connectionName;
+            if (!graphsByConnection.has(connName)) {
+                graphsByConnection.set(connName, []);
+            }
+            graphsByConnection.get(connName).push(node);
+        }
+        // Convert to BuildGraph array
+        const graphs = [];
+        for (const [connectionName, nodes] of graphsByConnection) {
+            graphs.push({ connectionName, nodes: [nodes] });
+        }
+        return { graphs, sources: sourcesMap };
+    }
+}
+exports.Model = Model;
+// =============================================================================
+// 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.
+ */
+class PersistSource {
+    constructor(explore, model) {
+        this.explore = explore;
+        this.model = model;
+        const sd = explore.structDef;
+        if (!(0, model_1.isSourceDef)(sd)) {
+            throw new Error('Cannot create PersistSource from non-source type');
+        }
+        if (!(0, model_1.isPersistableSourceDef)(sd)) {
+            throw new Error(`Cannot persist source '${explore.name}' of type '${sd.type}'. ` +
+                'Only query_source and sql_select sources can be persisted.');
+        }
+        this.persistableDef = sd;
+    }
+    /**
+     * The name of this source.
+     */
+    get name() {
+        return this.explore.name;
+    }
+    /**
+     * The stable identity of this source: "sourceName@modelURL".
+     * Used as lookup key during compilation and in build graphs.
+     */
+    get sourceID() {
+        const id = this.persistableDef.sourceID;
+        if (!id) {
+            throw new Error(`PersistSource '${this.name}' has no sourceID. ` +
+                'This should not happen - sourceID is set at translation time.');
+        }
+        return id;
+    }
+    /**
+     * The underlying Explore.
+     */
+    get _explore() {
+        return this.explore;
+    }
+    /**
+     * The annotation on this source.
+     */
+    get annotation() {
+        return this.persistableDef.annotation;
+    }
+    /**
+     * Parse the source's tags.
+     */
+    tagParse(spec) {
+        return this.explore.tagParse(spec);
+    }
+    /**
+     * Get annotation taglines matching an optional prefix.
+     */
+    getTaglines(prefix) {
+        return this.explore.getTaglines(prefix);
+    }
+    /**
+     * The connection name for this source.
+     */
+    get connectionName() {
+        return this.persistableDef.connection;
+    }
+    /**
+     * The dialect name for this source.
+     */
+    get dialectName() {
+        return this.persistableDef.dialect;
+    }
+    /**
+     * The dialect for this source.
+     */
+    get dialect() {
+        return (0, dialect_1.getDialect)(this.dialectName);
+    }
+    /**
+     * 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, sql) {
+        return (0, source_def_utils_1.mkBuildID)(connectionDigest, sql);
+    }
+    /**
+     * 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) {
+        const sd = this.persistableDef;
+        const queryModel = this.model.queryModel;
+        if (sd.type === 'sql_select') {
+            return (0, model_1.getCompiledSQL)(sd, options !== null && options !== void 0 ? options : {}, path => this.dialect.quoteTablePath(path), (query, opts) => queryModel.compileQuery(query, opts).sql);
+        }
+        else {
+            const compiled = queryModel.compileQuery(sd.query, options);
+            return compiled.sql;
+        }
+    }
+    /**
+     * Get the underlying persistable source definition.
+     */
+    get _sourceDef() {
+        return this.persistableDef;
+    }
+    /**
+     * Get the Model this source belongs to.
+     */
+    get _model() {
+        return this.model;
+    }
+}
+exports.PersistSource = PersistSource;
+// =============================================================================
+// PreparedQuery
+// =============================================================================
+class PreparedQuery {
+    constructor(query, _model, problems, name) {
+        this._model = _model;
+        this.problems = problems;
+        this.name = name;
+        this._query = query;
+    }
+    get _modelDef() {
+        return this._model._modelDef;
+    }
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this._query.annotation, spec);
+    }
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this._query.annotation, prefix);
+    }
+    /**
+     * Generate the SQL for this query.
+     *
+     * @return A fully-prepared query (which contains the generated SQL).
+     */
+    get preparedResult() {
+        return this.getPreparedResult();
+    }
+    /**
+     * 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) {
+        const queryModel = this._model.queryModel;
+        const translatedQuery = queryModel.compileQuery(this._query, options);
+        return new PreparedResult({
+            ...translatedQuery,
+            queryName: this.name || translatedQuery.queryName,
+        }, this._modelDef);
+    }
+    get dialect() {
+        const sourceRef = this._query.structRef;
+        const source = typeof sourceRef === 'string'
+            ? this._modelDef.contents[sourceRef]
+            : sourceRef;
+        if (!(0, model_1.isSourceDef)(source)) {
+            throw new Error('Invalid source for query');
+        }
+        return source.dialect;
+    }
+    /**
+     * 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) {
+        return this;
+    }
+    /**
+     * Get the Model this query belongs to.
+     */
+    get model() {
+        return this._model;
+    }
+}
+exports.PreparedQuery = PreparedQuery;
+// =============================================================================
+// PreparedResult
+// =============================================================================
+class PreparedResult {
+    constructor(query, modelDef) {
+        this.modelDef = modelDef;
+        this.inner = query;
+    }
+    static fromJson({ query, modelDef, }) {
+        if (!query || !modelDef) {
+            throw new Error('Missing required properties in JSON data');
+        }
+        return new PreparedResult(query, modelDef);
+    }
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this.inner.annotation, spec);
+    }
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this.inner.annotation, prefix);
+    }
+    get annotation() {
+        return this.inner.annotation;
+    }
+    get modelAnnotation() {
+        return this.modelDef.annotation;
+    }
+    get modelTag() {
+        return (0, annotation_1.annotationToTag)(this.modelDef.annotation).tag;
+    }
+    /**
+     * @return The name of the connection this query should be run against.
+     */
+    get connectionName() {
+        return this.inner.connectionName;
+    }
+    get _rawQuery() {
+        return this.inner;
+    }
+    get _modelDef() {
+        return this.modelDef;
+    }
+    /**
+     * @return The SQL that should be run against the SQL runner
+     * with the connection name `this.getConnectionName()`.
+     */
+    get sql() {
+        return this.inner.sql;
+    }
+    /**
+     * @return The `Explore` representing the data that will be returned by running this query.
+     */
+    get resultExplore() {
+        if (this.inner.structs.length === 0) {
+            throw new Error('Malformed query result.');
+        }
+        const explore = this.inner.structs[this.inner.structs.length - 1];
+        const namedExplore = {
+            ...explore,
+            annotation: this.inner.annotation,
+            name: this.inner.queryName || explore.name,
+        };
+        try {
+            return new Explore(namedExplore, this.sourceExplore);
+        }
+        catch (error) {
+            return new Explore(namedExplore);
+        }
+    }
+    get sourceExplore() {
+        const name = this.inner.sourceExplore;
+        const explore = this.modelDef.contents[name];
+        if (explore && (0, model_1.isSourceDef)(explore)) {
+            return new Explore(explore);
+        }
+    }
+    get _sourceExploreName() {
+        return this.inner.sourceExplore;
+    }
+    get _sourceArguments() {
+        return this.inner.sourceArguments;
+    }
+    get _sourceFilters() {
+        return this.inner.sourceFilters || [];
+    }
+    /**
+     * @return Whether this result has a schema. DDL statements (INSTALL, LOAD,
+     * CREATE SECRET, etc.) do not return a schema.
+     */
+    get hasSchema() {
+        return this.inner.structs.length > 0;
+    }
+}
+exports.PreparedResult = PreparedResult;
+//# sourceMappingURL=core.js.map