@malloydata/malloy 0.0.191-dev240927163326 → 0.0.191-dev240927225523

package/dist/malloy.d.ts

@@ -2,7 +2,7 @@
 import { RunSQLOptions } from './run_sql_options';
 import { DocumentCompletion as DocumentCompletionDefinition, DocumentSymbol as DocumentSymbolDefinition, LogMessage, MalloyTranslator } from './lang';
 import { DocumentHelpContext } from './lang/parse-tree-walkers/document-help-context-walker';
-import { CompiledQuery, DocumentLocation, DocumentReference, FieldBooleanDef, FieldDateDef, FieldJSONDef, FieldNumberDef, FieldStringDef, FieldTimestampDef, FieldTypeDef, FilterCondition, Query as InternalQuery, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQuery, QueryData, QueryDataRow, QueryResult, SQLBlock, SQLBlockSource, SQLBlockStructDef, SearchIndexResult, SearchValueMapResult, StructDef, TurtleDef, FeldNativeUnsupportedDef, QueryRunStats, ImportLocation, Annotation } from './model';
+import { CompiledQuery, DocumentLocation, DocumentReference, FieldBooleanDef, FieldDateDef, FieldJSONDef, FieldNumberDef, FieldStringDef, FieldTimestampDef, FieldTypeDef, FilterCondition, Query as InternalQuery, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQuery, QueryData, QueryDataRow, QueryResult, SQLBlock, SQLBlockSource, SQLBlockStructDef, SearchIndexResult, SearchValueMapResult, StructDef, TurtleDef, FeldNativeUnsupportedDef, QueryRunStats, ImportLocation, Annotation, QueryToMaterialize, PrepareResultOptions } from './model';
 import { ModelString, ModelURL, QueryString, QueryURL, URLReader } from './runtime_types';
 import { Connection, InfoConnection, LookupConnection } from './connection/types';
 import { Tag, TagParse, TagParseSpec, Taggable } from './tags';
@@ -61,13 +61,15 @@ export declare class Malloy {
      * @param model A compiled model to build upon (optional).
      * @return A (promise of a) compiled `Model`.
      */
-    static compile({ urlReader, connections, parse, model, refreshSchemaCache, noThrowOnError, }: {
+    static compile({ urlReader, connections, parse, model, refreshSchemaCache, noThrowOnError, replaceMaterializedReferences, }: {
         urlReader: URLReader;
         connections: LookupConnection<InfoConnection>;
         parse: Parse;
         model?: Model;
-    } & CompileOptions): Promise<Model>;
-    static compileSQLBlock(partialModel: ModelDef | undefined, toCompile: SQLBlockSource): SQLBlock;
+    } & CompileOptions & PrepareResultOptions): Promise<Model>;
+    static compileSQLBlock(partialModel: ModelDef | undefined, toCompile: SQLBlockSource, options?: {
+        replaceMaterializedReferences?: boolean;
+    }): SQLBlock;
     /**
      * Run a fully-prepared query.
      *
@@ -218,6 +220,12 @@ export declare class Model implements Taggable {
      * @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.
      *
@@ -257,6 +265,7 @@ export declare class PreparedQuery implements Taggable {
      * @return A fully-prepared query (which contains the generated SQL).
      */
     get preparedResult(): PreparedResult;
+    getPreparedResult(options?: PrepareResultOptions): PreparedResult;
     get dialect(): string;
     /**
      * Get the flattened version of a query -- one that does not have a `pipeHead`.
@@ -453,6 +462,7 @@ export declare class PreparedResult implements Taggable {
      * with the connection name `this.getConnectionName()`.
      */
     get sql(): string;
+    get dependenciesToMaterialize(): Record<string, QueryToMaterialize> | undefined;
     /**
      * @return The `Explore` representing the data that will be returned by running this query.
      */
@@ -742,8 +752,8 @@ export declare class Runtime {
      * @return A `ModelMaterializer` capable of materializing the requested model,
      * or loading further related objects.
      */
-    loadModel(source: ModelURL | ModelString, options?: ParseOptions & CompileOptions): ModelMaterializer;
-    _loadModelFromModelDef(modelDef: ModelDef): ModelMaterializer;
+    loadModel(source: ModelURL | ModelString, options?: ParseOptions & CompileOptions & PrepareResultOptions): ModelMaterializer;
+    _loadModelFromModelDef(modelDef: ModelDef, options?: PrepareResultOptions): ModelMaterializer;
     /**
      * Load a Malloy query by URL or contents.
      *
@@ -751,7 +761,7 @@ export declare class Runtime {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQuery(query: QueryURL | QueryString, options?: ParseOptions & CompileOptions): QueryMaterializer;
+    loadQuery(query: QueryURL | QueryString, options?: ParseOptions & CompileOptions & PrepareResultOptions): QueryMaterializer;
     /**
      * Load a Malloy query by the URL or contents of a Malloy model document
      * and the index of an unnamed query contained in the model.
@@ -761,7 +771,7 @@ export declare class Runtime {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQueryByIndex(model: ModelURL | ModelString, index: number, options?: ParseOptions & CompileOptions): QueryMaterializer;
+    loadQueryByIndex(model: ModelURL | ModelString, index: number, options?: ParseOptions & CompileOptions & PrepareResultOptions): QueryMaterializer;
     /**
      * Load a Malloy query by the URL or contents of a Malloy model document
      * and the name of a query contained in the model.
@@ -771,7 +781,7 @@ export declare class Runtime {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQueryByName(model: ModelURL | ModelString, name: string, options?: ParseOptions & CompileOptions): QueryMaterializer;
+    loadQueryByName(model: ModelURL | ModelString, name: string, options?: ParseOptions & CompileOptions & PrepareResultOptions): QueryMaterializer;
     /**
      * Load a SQL block by the URL or contents of a Malloy model document
      * and the name of a query contained in the model.
@@ -781,7 +791,7 @@ export declare class Runtime {
      * @return A `SQLBlockMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadSQLBlockByName(model: ModelURL | ModelString, name: string, options?: ParseOptions & CompileOptions): SQLBlockMaterializer;
+    loadSQLBlockByName(model: ModelURL | ModelString, name: string, options?: ParseOptions & CompileOptions & PrepareResultOptions): SQLBlockMaterializer;
     /**
      * Load a SQL block by the URL or contents of a Malloy model document
      * and the name of a query contained in the model.
@@ -864,8 +874,8 @@ declare class FluentState<T> {
     constructor(runtime: Runtime, materialize: () => Promise<T>);
     protected materialize(): Promise<T>;
     protected rematerialize(): Promise<T>;
-    protected makeQueryMaterializer(materialize: () => Promise<PreparedQuery>): QueryMaterializer;
-    protected makeExploreMaterializer(materialize: () => Promise<Explore>): ExploreMaterializer;
+    protected makeQueryMaterializer(materialize: () => Promise<PreparedQuery>, options?: PrepareResultOptions): QueryMaterializer;
+    protected makeExploreMaterializer(materialize: () => Promise<Explore>, options?: PrepareResultOptions): ExploreMaterializer;
     protected makePreparedResultMaterializer(materialize: () => Promise<PreparedResult>): PreparedResultMaterializer;
     protected makeSQLBlockMaterializer(materialize: () => Promise<SQLBlockStructDef>): SQLBlockMaterializer;
 }
@@ -875,13 +885,16 @@ declare class FluentState<T> {
  * queries or explores (via e.g. `loadFinalQuery()`, `loadQuery`, `loadExploreByName`, etc.).
  */
 export declare class ModelMaterializer extends FluentState<Model> {
+    protected runtime: Runtime;
+    private readonly replaceMaterializedReferences;
+    constructor(runtime: Runtime, materialize: () => Promise<Model>, options?: PrepareResultOptions);
     /**
      * Load the final (unnamed) Malloy query contained within this loaded `Model`.
      *
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadFinalQuery(): QueryMaterializer;
+    loadFinalQuery(options?: PrepareResultOptions): QueryMaterializer;
     /**
      * Load an unnamed query contained within this loaded `Model` by index.
      *
@@ -889,7 +902,7 @@ export declare class ModelMaterializer extends FluentState<Model> {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQueryByIndex(index: number): QueryMaterializer;
+    loadQueryByIndex(index: number, options?: PrepareResultOptions): QueryMaterializer;
     /**
      * Load a query contained within this loaded `Model` by its name.
      *
@@ -897,7 +910,7 @@ export declare class ModelMaterializer extends FluentState<Model> {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQueryByName(name: string): QueryMaterializer;
+    loadQueryByName(name: string, options?: PrepareResultOptions): QueryMaterializer;
     /**
      * Load a query against this loaded `Model` by its URL or contents.
      *
@@ -905,7 +918,7 @@ export declare class ModelMaterializer extends FluentState<Model> {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQuery(query: QueryString | QueryURL, options?: ParseOptions & CompileOptions): QueryMaterializer;
+    loadQuery(query: QueryString | QueryURL, options?: ParseOptions & CompileOptions & PrepareResultOptions): QueryMaterializer;
     /**
      * Extend a Malloy model by URL or contents.
      *
@@ -913,7 +926,7 @@ export declare class ModelMaterializer extends FluentState<Model> {
      * @return A `ModelMaterializer` capable of materializing the requested model,
      * or loading further related objects.
      */
-    extendModel(query: QueryString | QueryURL, options?: ParseOptions & CompileOptions): ModelMaterializer;
+    extendModel(query: QueryString | QueryURL, options?: ParseOptions & CompileOptions & PrepareResultOptions): ModelMaterializer;
     search(sourceName: string, searchTerm: string, limit?: number, searchField?: string | undefined): Promise<SearchIndexResult[] | undefined>;
     searchValueMap(sourceName: string, limit?: number, options?: ParseOptions): Promise<SearchValueMapResult[] | undefined>;
     /**
@@ -977,7 +990,7 @@ export declare class ModelMaterializer extends FluentState<Model> {
      * TODO feature-sql-block Should named SQL blocks be indexable? This is not the way unnamed queries work.
      */
     getSQLBlockByIndex(index: number): Promise<SQLBlockStructDef>;
-    _loadQueryFromQueryDef(query: InternalQuery): QueryMaterializer;
+    _loadQueryFromQueryDef(query: InternalQuery, options?: PrepareResultOptions): QueryMaterializer;
     /**
      * Load an explore contained within this loaded `Model` by name.
      *
@@ -1006,32 +1019,35 @@ export declare class ModelMaterializer extends FluentState<Model> {
  * prepared results or run the query (via e.g. `loadPreparedResult()` or `run()`).
  */
 export declare class QueryMaterializer extends FluentState<PreparedQuery> {
+    protected runtime: Runtime;
+    private readonly replaceMaterializedReferences;
+    constructor(runtime: Runtime, materialize: () => Promise<PreparedQuery>, options?: PrepareResultOptions);
     /**
      * Run this loaded `Query`.
      *
      * @return The query results from running this loaded query.
      */
-    run(options?: RunSQLOptions): Promise<Result>;
-    runStream(options?: RunSQLOptions): AsyncIterableIterator<DataRecord>;
+    run(options?: RunSQLOptions & PrepareResultOptions): Promise<Result>;
+    runStream(options?: RunSQLOptions & PrepareResultOptions): AsyncIterableIterator<DataRecord>;
     /**
      * Load the prepared result of this loaded query.
      *
      * @return A `PreparedResultMaterializer` capable of materializing the requested
      * prepared query or running it.
      */
-    loadPreparedResult(): PreparedResultMaterializer;
+    loadPreparedResult(options?: PrepareResultOptions): PreparedResultMaterializer;
     /**
      * Materialize the prepared result of this loaded query.
      *
      * @return A promise of the prepared result of this loaded query.
      */
-    getPreparedResult(): Promise<PreparedResult>;
+    getPreparedResult(options?: PrepareResultOptions): Promise<PreparedResult>;
     /**
      * Materialize the SQL of this loaded query.
      *
      * @return A promise of the SQL string.
      */
-    getSQL(): Promise<string>;
+    getSQL(options?: PrepareResultOptions): Promise<string>;
     /**
      * Materialize this loaded query.
      *
@@ -1043,7 +1059,7 @@ export declare class QueryMaterializer extends FluentState<PreparedQuery> {
      *
      * @return The estimated cost of running this loaded query.
      */
-    estimateQueryCost(): Promise<QueryRunStats>;
+    estimateQueryCost(options?: PrepareResultOptions): Promise<QueryRunStats>;
 }
 /**
  * An object representing the task of loading a `PreparedResult`, capable of
@@ -1108,6 +1124,9 @@ export declare class SQLBlockMaterializer extends FluentState<SQLBlockStructDef>
  * related queries.
  */
 export declare class ExploreMaterializer extends FluentState<Explore> {
+    protected runtime: Runtime;
+    private readonly replaceMaterializedReferences;
+    constructor(runtime: Runtime, materialize: () => Promise<Explore>, options?: PrepareResultOptions);
     /**
      * Load a query contained within this loaded explore.
      *
@@ -1115,7 +1134,7 @@ export declare class ExploreMaterializer extends FluentState<Explore> {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQueryByName(name: string): QueryMaterializer;
+    loadQueryByName(name: string, options?: PrepareResultOptions): QueryMaterializer;
     /**
      * Materialize a query contained within this loaded explore.
      *

package/dist/malloy.js

@@ -80,7 +80,7 @@ class Malloy {
      * @param model A compiled model to build upon (optional).
      * @return A (promise of a) compiled `Model`.
      */
-    static async compile({ urlReader, connections, parse, model, refreshSchemaCache, noThrowOnError, }) {
+    static async compile({ urlReader, connections, parse, model, refreshSchemaCache, noThrowOnError, replaceMaterializedReferences, }) {
         var _a, _b, _c, _d;
         let refreshTimestamp;
         if (refreshSchemaCache) {
@@ -177,7 +177,7 @@ class Malloy {
                     const connectionName = toCompile.connection;
                     try {
                         const conn = await connections.lookupConnection(connectionName);
-                        const expanded = Malloy.compileSQLBlock(result.partialModel, toCompile);
+                        const expanded = Malloy.compileSQLBlock(result.partialModel, toCompile, { replaceMaterializedReferences });
                         const resolved = await conn.fetchSchemaForSQLBlock(expanded, {
                             refreshTimestamp,
                             modelAnnotation,
@@ -204,7 +204,7 @@ class Malloy {
             }
         }
     }
-    static compileSQLBlock(partialModel, toCompile) {
+    static compileSQLBlock(partialModel, toCompile, options) {
         let queryModel = undefined;
         let selectStr = '';
         let parenAlready = false;
@@ -221,7 +221,7 @@ class Malloy {
                     }
                     queryModel = new model_1.QueryModel(partialModel);
                 }
-                const compiledSql = queryModel.compileQuery(segment, false).sql;
+                const compiledSql = queryModel.compileQuery(segment, options, false).sql;
                 selectStr += parenAlready ? compiledSql : `(${compiledSql})`;
                 parenAlready = false;
             }
@@ -446,6 +446,14 @@ class 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.queryList.length === 0) {
             throw new Error('Model has no queries.');
         }
@@ -516,8 +524,11 @@ class PreparedQuery {
      * @return A fully-prepared query (which contains the generated SQL).
      */
     get preparedResult() {
+        return this.getPreparedResult();
+    }
+    getPreparedResult(options) {
         const queryModel = new model_1.QueryModel(this._modelDef);
-        const translatedQuery = queryModel.compileQuery(this._query);
+        const translatedQuery = queryModel.compileQuery(this._query, options);
         return new PreparedResult({
             ...translatedQuery,
             queryName: this.name || translatedQuery.queryName,
@@ -787,6 +798,9 @@ class PreparedResult {
     get sql() {
         return this.inner.sql;
     }
+    get dependenciesToMaterialize() {
+        return this.inner.dependenciesToMaterialize;
+    }
     /**
      * @return The `Explore` representing the data that will be returned by running this query.
      */
@@ -1603,17 +1617,18 @@ class Runtime {
                 parse,
                 refreshSchemaCache,
                 noThrowOnError,
+                replaceMaterializedReferences: options === null || options === void 0 ? void 0 : options.replaceMaterializedReferences,
             });
-        });
+        }, options);
     }
     // TODO Consider formalizing this. Perhaps as a `withModel` method,
     //      as well as a `Model.fromModelDefinition` if we choose to expose
     //      `ModelDef` to the world formally. For now, this should only
     //      be used in tests.
-    _loadModelFromModelDef(modelDef) {
+    _loadModelFromModelDef(modelDef, options) {
         return new ModelMaterializer(this, async () => {
             return new Model(modelDef, [], [], [], []);
-        });
+        }, options);
     }
     /**
      * Load a Malloy query by URL or contents.
@@ -1635,7 +1650,7 @@ class Runtime {
      * or loading further related objects.
      */
     loadQueryByIndex(model, index, options) {
-        return this.loadModel(model, options).loadQueryByIndex(index);
+        return this.loadModel(model, options).loadQueryByIndex(index, options);
     }
     /**
      * Load a Malloy query by the URL or contents of a Malloy model document
@@ -1647,7 +1662,7 @@ class Runtime {
      * or loading further related objects.
      */
     loadQueryByName(model, name, options) {
-        return this.loadModel(model, options).loadQueryByName(name);
+        return this.loadModel(model, options).loadQueryByName(name, options);
     }
     /**
      * Load a SQL block by the URL or contents of a Malloy model document
@@ -1796,11 +1811,11 @@ class FluentState {
         this.materialized = this._materialize();
         return this.materialized;
     }
-    makeQueryMaterializer(materialize) {
-        return new QueryMaterializer(this.runtime, materialize);
+    makeQueryMaterializer(materialize, options) {
+        return new QueryMaterializer(this.runtime, materialize, options);
     }
-    makeExploreMaterializer(materialize) {
-        return new ExploreMaterializer(this.runtime, materialize);
+    makeExploreMaterializer(materialize, options) {
+        return new ExploreMaterializer(this.runtime, materialize, options);
     }
     makePreparedResultMaterializer(materialize) {
         return new PreparedResultMaterializer(this.runtime, materialize);
@@ -1815,15 +1830,25 @@ class FluentState {
  * queries or explores (via e.g. `loadFinalQuery()`, `loadQuery`, `loadExploreByName`, etc.).
  */
 class ModelMaterializer extends FluentState {
+    constructor(runtime, materialize, options) {
+        var _a;
+        super(runtime, materialize);
+        this.runtime = runtime;
+        this.replaceMaterializedReferences =
+            (_a = options === null || options === void 0 ? void 0 : options.replaceMaterializedReferences) !== null && _a !== void 0 ? _a : false;
+    }
     /**
      * Load the final (unnamed) Malloy query contained within this loaded `Model`.
      *
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadFinalQuery() {
+    loadFinalQuery(options) {
         return this.makeQueryMaterializer(async () => {
-            return (await this.materialize()).preparedQuery;
+            return (await this.materialize()).getPreparedQuery();
+        }, {
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
         });
     }
     /**
@@ -1833,9 +1858,12 @@ class ModelMaterializer extends FluentState {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQueryByIndex(index) {
+    loadQueryByIndex(index, options) {
         return this.makeQueryMaterializer(async () => {
             return (await this.materialize()).getPreparedQueryByIndex(index);
+        }, {
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
         });
     }
     /**
@@ -1845,9 +1873,12 @@ class ModelMaterializer extends FluentState {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQueryByName(name) {
+    loadQueryByName(name, options) {
         return this.makeQueryMaterializer(async () => {
             return (await this.materialize()).getPreparedQueryByName(name);
+        }, {
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
         });
     }
     /**
@@ -1860,6 +1891,7 @@ class ModelMaterializer extends FluentState {
     loadQuery(query, options) {
         const { refreshSchemaCache, noThrowOnError } = options || {};
         return this.makeQueryMaterializer(async () => {
+            var _a;
             const urlReader = this.runtime.urlReader;
             const connections = this.runtime.connections;
             if (this.runtime.isTestRuntime) {
@@ -1888,6 +1920,7 @@ class ModelMaterializer extends FluentState {
                 model,
                 refreshSchemaCache,
                 noThrowOnError,
+                replaceMaterializedReferences: (_a = options === null || options === void 0 ? void 0 : options.replaceMaterializedReferences) !== null && _a !== void 0 ? _a : this.replaceMaterializedReferences,
             });
             return queryModel.preparedQuery;
         });
@@ -1909,6 +1942,7 @@ class ModelMaterializer extends FluentState {
             }
         }
         return new ModelMaterializer(this.runtime, async () => {
+            var _a;
             const urlReader = this.runtime.urlReader;
             const connections = this.runtime.connections;
             const parse = query instanceof URL
@@ -1929,9 +1963,10 @@ class ModelMaterializer extends FluentState {
                 model,
                 refreshSchemaCache: options === null || options === void 0 ? void 0 : options.refreshSchemaCache,
                 noThrowOnError: options === null || options === void 0 ? void 0 : options.noThrowOnError,
+                replaceMaterializedReferences: (_a = options === null || options === void 0 ? void 0 : options.replaceMaterializedReferences) !== null && _a !== void 0 ? _a : this.replaceMaterializedReferences,
             });
             return queryModel;
-        });
+        }, options);
     }
     async search(sourceName, searchTerm, limit = 1000, searchField = undefined) {
         const model = await this.materialize();
@@ -2059,10 +2094,13 @@ class ModelMaterializer extends FluentState {
     //      as well as a `PreparedQuery.fromQueryDefinition` if we choose to expose
     //      `InternalQuery` to the world formally. For now, this should only
     //      be used in tests.
-    _loadQueryFromQueryDef(query) {
+    _loadQueryFromQueryDef(query, options) {
         return this.makeQueryMaterializer(async () => {
             const model = await this.materialize();
             return new PreparedQuery(query, model._modelDef, model.problems);
+        }, {
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
         });
     }
     /**
@@ -2075,6 +2113,8 @@ class ModelMaterializer extends FluentState {
     loadExploreByName(name) {
         return this.makeExploreMaterializer(async () => {
             return (await this.materialize()).getExploreByName(name);
+        }, {
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
         });
     }
     /**
@@ -2102,6 +2142,13 @@ exports.ModelMaterializer = ModelMaterializer;
  * prepared results or run the query (via e.g. `loadPreparedResult()` or `run()`).
  */
 class QueryMaterializer extends FluentState {
+    constructor(runtime, materialize, options) {
+        var _a;
+        super(runtime, materialize);
+        this.runtime = runtime;
+        this.replaceMaterializedReferences =
+            (_a = options === null || options === void 0 ? void 0 : options.replaceMaterializedReferences) !== null && _a !== void 0 ? _a : false;
+    }
     /**
      * Run this loaded `Query`.
      *
@@ -2109,12 +2156,18 @@ class QueryMaterializer extends FluentState {
      */
     async run(options) {
         const connections = this.runtime.connections;
-        const preparedResult = await this.getPreparedResult();
+        const preparedResult = await this.getPreparedResult({
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
+        });
         const finalOptions = runSQLOptionsWithAnnotations(preparedResult, options);
         return Malloy.run({ connections, preparedResult, options: finalOptions });
     }
     async *runStream(options) {
-        const preparedResult = await this.getPreparedResult();
+        const preparedResult = await this.getPreparedResult({
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
+        });
         const connections = this.runtime.connections;
         const finalOptions = runSQLOptionsWithAnnotations(preparedResult, options);
         const stream = Malloy.runStream({
@@ -2132,9 +2185,12 @@ class QueryMaterializer extends FluentState {
      * @return A `PreparedResultMaterializer` capable of materializing the requested
      * prepared query or running it.
      */
-    loadPreparedResult() {
+    loadPreparedResult(options) {
         return this.makePreparedResultMaterializer(async () => {
-            return (await this.materialize()).preparedResult;
+            return (await this.materialize()).getPreparedResult({
+                replaceMaterializedReferences: this.replaceMaterializedReferences,
+                ...options,
+            });
         });
     }
     /**
@@ -2142,16 +2198,22 @@ class QueryMaterializer extends FluentState {
      *
      * @return A promise of the prepared result of this loaded query.
      */
-    getPreparedResult() {
-        return this.loadPreparedResult().getPreparedResult();
+    getPreparedResult(options) {
+        return this.loadPreparedResult({
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
+        }).getPreparedResult();
     }
     /**
      * Materialize the SQL of this loaded query.
      *
      * @return A promise of the SQL string.
      */
-    async getSQL() {
-        return (await this.getPreparedResult()).sql;
+    async getSQL(options) {
+        return (await this.getPreparedResult({
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
+        })).sql;
     }
     /**
      * Materialize this loaded query.
@@ -2166,9 +2228,12 @@ class QueryMaterializer extends FluentState {
      *
      * @return The estimated cost of running this loaded query.
      */
-    async estimateQueryCost() {
+    async estimateQueryCost(options) {
         const connections = this.runtime.connections;
-        const preparedResult = await this.getPreparedResult();
+        const preparedResult = await this.getPreparedResult({
+            replaceMaterializedReferences: this.replaceMaterializedReferences,
+            ...options,
+        });
         return Malloy.estimateQueryCost({ connections, preparedResult });
     }
 }
@@ -2290,6 +2355,13 @@ exports.SQLBlockMaterializer = SQLBlockMaterializer;
  * related queries.
  */
 class ExploreMaterializer extends FluentState {
+    constructor(runtime, materialize, options) {
+        var _a;
+        super(runtime, materialize);
+        this.runtime = runtime;
+        this.replaceMaterializedReferences =
+            (_a = options === null || options === void 0 ? void 0 : options.replaceMaterializedReferences) !== null && _a !== void 0 ? _a : false;
+    }
     /**
      * Load a query contained within this loaded explore.
      *
@@ -2297,10 +2369,10 @@ class ExploreMaterializer extends FluentState {
      * @return A `QueryMaterializer` capable of materializing the requested query, running it,
      * or loading further related objects.
      */
-    loadQueryByName(name) {
+    loadQueryByName(name, options) {
         return this.makeQueryMaterializer(async () => {
             return (await this.materialize()).getQueryByName(name);
-        });
+        }, options);
     }
     /**
      * Materialize a query contained within this loaded explore.

package/dist/model/malloy_query.d.ts

@@ -1,5 +1,5 @@
 import { Dialect, DialectFieldList } from '../dialect';
-import { AggregateFunctionType, Annotation, CompiledQuery, Expr, FieldDef, Filtered, FunctionOverloadDef, FunctionParameterDef, JoinRelationship, ModelDef, OrderBy, OutputFieldNode, Parameter, ParameterNode, PipeSegment, Query, QueryFieldDef, QuerySegment, ResultMetadataDef, ResultStructMetadataDef, SearchIndexResult, SegmentFieldDef, StructDef, StructRef, TurtleDef, FunctionOrderBy, Argument, AggregateExpr, FilterCondition, GenericSQLExpr, FieldnameNode, FunctionCallNode, UngroupNode, SourceReferenceNode, PickExpr, SpreadExpr, FilteredExpr } from './malloy_types';
+import { AggregateFunctionType, Annotation, CompiledQuery, Expr, FieldDef, Filtered, FunctionOverloadDef, FunctionParameterDef, JoinRelationship, ModelDef, OrderBy, OutputFieldNode, Parameter, ParameterNode, PipeSegment, Query, QueryFieldDef, QuerySegment, ResultMetadataDef, ResultStructMetadataDef, SearchIndexResult, SegmentFieldDef, StructDef, StructRef, TurtleDef, FunctionOrderBy, Argument, AggregateExpr, FilterCondition, GenericSQLExpr, FieldnameNode, FunctionCallNode, UngroupNode, SourceReferenceNode, PickExpr, SpreadExpr, FilteredExpr, QueryToMaterialize, PrepareResultOptions } from './malloy_types';
 import { Connection } from '../connection/types';
 import { AndChain } from './utils';
 import { QueryInfo } from '../dialect/dialect';
@@ -27,6 +27,7 @@ declare class StageWriter {
     withs: string[];
     udfs: string[];
     pdts: string[];
+    dependenciesToMaterialize: Record<string, QueryToMaterialize>;
     stagePrefix: string;
     useCTE: boolean;
     constructor(useCTE: boolean | undefined, parent: StageWriter | undefined);
@@ -34,6 +35,7 @@ declare class StageWriter {
     root(): StageWriter;
     addStage(sql: string): string;
     addUDF(stageWriter: StageWriter, dialect: Dialect, structDef: StructDef): string;
+    addMaterializedQuery(fieldName: string, query: Query): string;
     addPDT(baseName: string, dialect: Dialect): string;
     combineStages(includeLastStage: boolean): {
         sql: string;
@@ -290,6 +292,7 @@ declare class QueryQuery extends QueryField {
 /** Structure object as it is used to build a query */
 declare class QueryStruct extends QueryNode {
     readonly sourceArguments: Record<string, Argument> | undefined;
+    readonly prepareResultOptions?: PrepareResultOptions | undefined;
     fieldDef: StructDef;
     parent: QueryStruct | undefined;
     model: QueryModel;
@@ -297,7 +300,7 @@ declare class QueryStruct extends QueryNode {
     pathAliasMap: Map<string, string>;
     dialect: Dialect;
     connectionName: string;
-    constructor(fieldDef: StructDef, sourceArguments: Record<string, Argument> | undefined, parent: ParentQueryStruct | ParentQueryModel);
+    constructor(fieldDef: StructDef, sourceArguments: Record<string, Argument> | undefined, parent: ParentQueryStruct | ParentQueryModel, prepareResultOptions?: PrepareResultOptions | undefined);
     resolveParentParameterReferences(param: Parameter): Parameter;
     private _arguments;
     arguments(): Record<string, Argument>;
@@ -354,9 +357,9 @@ export declare class QueryModel {
     constructor(modelDef: ModelDef | undefined);
     loadModelFromDef(modelDef: ModelDef): void;
     getStructByName(name: string): QueryStruct;
-    getStructFromRef(structRef: StructRef, sourceArguments: Record<string, Argument> | undefined): QueryStruct;
-    loadQuery(query: Query, stageWriter: StageWriter | undefined, emitFinalStage?: boolean, isJoinedSubquery?: boolean): QueryResults;
-    compileQuery(query: Query, finalize?: boolean): CompiledQuery;
+    getStructFromRef(structRef: StructRef, sourceArguments: Record<string, Argument> | undefined, prepareResultOptions?: PrepareResultOptions): QueryStruct;
+    loadQuery(query: Query, stageWriter: StageWriter | undefined, prepareResultOptions?: PrepareResultOptions, emitFinalStage?: boolean, isJoinedSubquery?: boolean): QueryResults;
+    compileQuery(query: Query, prepareResultOptions?: PrepareResultOptions, finalize?: boolean): CompiledQuery;
     exploreSearchSQLMap: Map<any, any>;
     searchIndex(connection: Connection, explore: string, searchValue: string, limit?: number, searchField?: string | undefined): Promise<SearchIndexResult[] | undefined>;
 }

package/dist/model/malloy_query.js

@@ -27,6 +27,7 @@ const dialect_1 = require("../dialect");
 const standardsql_1 = require("../dialect/standardsql/standardsql");
 const malloy_types_1 = require("./malloy_types");
 const utils_1 = require("./utils");
+const tags_1 = require("../tags");
 function pathToCol(path) {
     return path.map(el => encodeURIComponent(el)).join('/');
 }
@@ -68,6 +69,7 @@ class StageWriter {
         this.withs = [];
         this.udfs = [];
         this.pdts = [];
+        this.dependenciesToMaterialize = {};
         this.stagePrefix = '__stage';
         this.useCTE = useCTE;
     }
@@ -104,9 +106,34 @@ class StageWriter {
         this.root().udfs.push(sql);
         return id;
     }
+    addMaterializedQuery(fieldName, query) {
+        var _a;
+        const name = query.name;
+        if (!name) {
+            throw new Error(`Source ${fieldName} on a unnamed query that is tagged as materialize, only named queries can be materialized.`);
+        }
+        const path = (_a = query.location) === null || _a === void 0 ? void 0 : _a.url;
+        if (!path) {
+            throw new Error(`Trying to materialize query ${name}, but its path is not set.`);
+        }
+        // Creating an object that should uniquely identify a query within a Malloy model repo.
+        const queryRep = {
+            path: path,
+            source: undefined,
+            queryName: name,
+        };
+        const id = (0, utils_1.generateHash)(JSON.stringify(queryRep));
+        const uniqueName = `${name}-${id}`;
+        this.root().dependenciesToMaterialize[uniqueName] = {
+            ...queryRep,
+            id,
+        };
+        return uniqueName;
+    }
     addPDT(baseName, dialect) {
         const sql = this.combineStages(false).sql + this.withs[this.withs.length - 1];
-        const tableName = 'scratch.' + baseName + (0, utils_1.generateHash)(sql);
+        const name = baseName + (0, utils_1.generateHash)(sql);
+        const tableName = `scratch.${name}`;
         this.root().pdts.push(dialect.sqlCreateTableAsSelect(tableName, sql));
         return tableName;
     }
@@ -1562,7 +1589,7 @@ class QueryQuery extends QueryField {
             parent = new QueryStruct({
                 ...sourceDef,
                 fields: [...sourceDef.fields, ...firstStage.extendSource],
-            }, parentStruct.sourceArguments, parent.parent ? { struct: parent } : { model: parent.model });
+            }, parentStruct.sourceArguments, parent.parent ? { struct: parent } : { model: parent.model }, parent.prepareResultOptions);
             turtleWithFilters = {
                 ...turtleWithFilters,
                 pipeline: [
@@ -2631,7 +2658,7 @@ class QueryQuery extends QueryField {
             structDef.structSource = { type: 'sql', method: 'nested' };
             const qs = new QueryStruct(structDef, undefined, {
                 model: this.parent.getModel(),
-            });
+            }, this.parent.prepareResultOptions);
             const q = QueryQuery.makeQuery(newTurtle, qs, stageWriter, this.isJoinedSubquery);
             pipeOut = q.generateSQLFromPipeline(stageWriter);
             // console.log(stageWriter.generateSQLStages());
@@ -2689,7 +2716,7 @@ class QueryQuery extends QueryField {
             for (const transform of pipeline) {
                 const s = new QueryStruct(structDef, undefined, {
                     model: this.parent.getModel(),
-                });
+                }, this.parent.prepareResultOptions);
                 const q = QueryQuery.makeQuery({ type: 'turtle', name: 'ignoreme', pipeline: [transform] }, s, stageWriter, this.isJoinedSubquery);
                 q.prepare(stageWriter);
                 lastStageName = q.generateSQL(stageWriter);
@@ -2954,9 +2981,10 @@ class QueryQueryIndex extends QueryQuery {
 }
 /** Structure object as it is used to build a query */
 class QueryStruct extends QueryNode {
-    constructor(fieldDef, sourceArguments, parent) {
+    constructor(fieldDef, sourceArguments, parent, prepareResultOptions) {
         super(fieldDef);
         this.sourceArguments = sourceArguments;
+        this.prepareResultOptions = prepareResultOptions;
         this.nameMap = new Map();
         this._arguments = undefined;
         this.setParent(parent);
@@ -3030,7 +3058,7 @@ class QueryStruct extends QueryNode {
                 case 'struct': {
                     this.addFieldToNameMap(as, new QueryStruct(field, undefined, {
                         struct: this,
-                    }));
+                    }, this.prepareResultOptions));
                     break;
                 }
                 // case "reduce" || "project" || "index": {
@@ -3161,7 +3189,7 @@ class QueryStruct extends QueryNode {
     resolveQueryFields() {
         if (this.fieldDef.structSource.type === 'query') {
             const structDef = this.model
-                .loadQuery(this.fieldDef.structSource.query, undefined)
+                .loadQuery(this.fieldDef.structSource.query, undefined, this.prepareResultOptions)
                 .structs.pop();
             // should never happen.
             if (!structDef) {
@@ -3235,6 +3263,7 @@ class QueryStruct extends QueryNode {
         }
     }
     structSourceSQL(stageWriter) {
+        var _a;
         switch (this.fieldDef.structSource.type) {
             case 'table': {
                 const tablePath = this.fieldDef.structSource.tablePath;
@@ -3257,17 +3286,18 @@ class QueryStruct extends QueryNode {
                 return '';
             case 'query': {
                 // cache derived table.
-                const name = (0, malloy_types_1.getIdentifier)(this.fieldDef);
-                // this is a hack for now.  Need some way to denote this table
-                //  should be cached.
-                if (name.includes('cache')) {
-                    const dtStageWriter = new StageWriter(true, stageWriter);
-                    this.model.loadQuery(this.fieldDef.structSource.query, dtStageWriter, false, false);
-                    return dtStageWriter.addPDT(name, this.dialect);
+                const clonedAnnotation = structuredClone(this.fieldDef.structSource.query.annotation);
+                if (clonedAnnotation) {
+                    clonedAnnotation.inherits = undefined;
+                }
+                const sourceTag = tags_1.Tag.annotationToTag(clonedAnnotation).tag;
+                if (((_a = this.prepareResultOptions) === null || _a === void 0 ? void 0 : _a.replaceMaterializedReferences) &&
+                    sourceTag.has('materialize')) {
+                    return stageWriter.addMaterializedQuery((0, malloy_types_1.getIdentifier)(this.fieldDef), this.fieldDef.structSource.query);
                 }
                 else {
                     // returns the stage name.
-                    return this.model.loadQuery(this.fieldDef.structSource.query, stageWriter, false, true // this is an intermediate stage.
+                    return this.model.loadQuery(this.fieldDef.structSource.query, stageWriter, this.prepareResultOptions, false, true // this is an intermediate stage.
                     ).lastStageName;
                 }
             }
@@ -3424,13 +3454,13 @@ class QueryModel {
             throw new Error(`Struct ${name} not found in model.`);
         }
     }
-    getStructFromRef(structRef, sourceArguments) {
+    getStructFromRef(structRef, sourceArguments, prepareResultOptions) {
         var _a;
         let structDef;
         if (typeof structRef === 'string') {
             const ret = this.getStructByName(structRef);
             if (sourceArguments !== undefined) {
-                return new QueryStruct(ret.fieldDef, sourceArguments, (_a = ret.parent) !== null && _a !== void 0 ? _a : { model: this });
+                return new QueryStruct(ret.fieldDef, sourceArguments, (_a = ret.parent) !== null && _a !== void 0 ? _a : { model: this }, prepareResultOptions);
             }
             return ret;
         }
@@ -3440,9 +3470,9 @@ class QueryModel {
         else {
             throw new Error('Broken for now');
         }
-        return new QueryStruct(structDef, sourceArguments, { model: this });
+        return new QueryStruct(structDef, sourceArguments, { model: this }, prepareResultOptions);
     }
-    loadQuery(query, stageWriter, emitFinalStage = false, isJoinedSubquery = false) {
+    loadQuery(query, stageWriter, prepareResultOptions, emitFinalStage = false, isJoinedSubquery = false) {
         const malloy = '';
         if (!stageWriter) {
             stageWriter = new StageWriter(true, undefined);
@@ -3453,7 +3483,7 @@ class QueryModel {
             pipeline: query.pipeline,
             filterList: query.filterList,
         };
-        const q = QueryQuery.makeQuery(turtleDef, this.getStructFromRef(query.structRef, query.sourceArguments), stageWriter, isJoinedSubquery);
+        const q = QueryQuery.makeQuery(turtleDef, this.getStructFromRef(query.structRef, query.sourceArguments, prepareResultOptions), stageWriter, isJoinedSubquery);
         const ret = q.generateSQLFromPipeline(stageWriter);
         if (emitFinalStage && q.parent.dialect.hasFinalStage) {
             // const fieldNames: string[] = [];
@@ -3471,10 +3501,10 @@ class QueryModel {
             connectionName: q.parent.connectionName,
         };
     }
-    compileQuery(query, finalize = true) {
+    compileQuery(query, prepareResultOptions, finalize = true) {
         let newModel;
         const m = newModel || this;
-        const ret = m.loadQuery(query, undefined, finalize, false);
+        const ret = m.loadQuery(query, undefined, prepareResultOptions, finalize, false);
         const sourceExplore = typeof query.structRef === 'string'
             ? query.structRef
             : // LTNOTE: the parser needs to capture the query before the |.  This will work
@@ -3492,6 +3522,7 @@ class QueryModel {
             lastStageName: ret.lastStageName,
             malloy: ret.malloy,
             sql: ret.stageWriter.generateSQLStages(),
+            dependenciesToMaterialize: ret.stageWriter.dependenciesToMaterialize,
             structs: ret.structs,
             sourceExplore,
             sourceFilters: query.filterList,
@@ -3533,7 +3564,7 @@ class QueryModel {
         // if we've compiled the SQL before use it otherwise
         let sqlPDT = this.exploreSearchSQLMap.get(explore);
         if (sqlPDT === undefined) {
-            sqlPDT = this.compileQuery(indexQuery, false).sql;
+            sqlPDT = this.compileQuery(indexQuery, undefined, false).sql;
             this.exploreSearchSQLMap.set(explore, sqlPDT);
         }
         let query = `SELECT

package/dist/model/malloy_types.d.ts

@@ -719,6 +719,12 @@ export interface DrillSource {
     sourceExplore: string;
     sourceFilters?: FilterCondition[];
 }
+export type QueryToMaterialize = {
+    id: string;
+    path: string;
+    source: string | undefined;
+    queryName: string;
+};
 export interface CompiledQuery extends DrillSource {
     structs: StructDef[];
     sql: string;
@@ -728,6 +734,7 @@ export interface CompiledQuery extends DrillSource {
     connectionName: string;
     queryTimezone?: string;
     annotation?: Annotation;
+    dependenciesToMaterialize?: Record<string, QueryToMaterialize>;
 }
 /** Result type for running a Malloy query. */
 export interface QueryResult extends CompiledQuery {
@@ -773,4 +780,7 @@ export interface SearchValueMapResult {
         weight: number;
     }[];
 }
+export interface PrepareResultOptions {
+    replaceMaterializedReferences?: boolean;
+}
 export {};

package/dist/run_sql_options.d.ts

@@ -4,5 +4,6 @@ export interface RunSQLOptions {
     abortSignal?: AbortSignal;
     modelAnnotation?: Annotation;
     queryAnnotation?: Annotation;
+    replaceMaterializedReferences?: boolean;
 }
 export type QueryOptionsReader = RunSQLOptions | (() => RunSQLOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/malloy",
-  "version": "0.0.191-dev240927163326",
+  "version": "0.0.191-dev240927225523",
   "license": "MIT",
   "exports": {
     ".": "./dist/index.js",