@malloydata/malloy 0.0.194 → 0.0.195-dev241003204819

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { LogMessage, TranslateResponse } from './lang';
 export { Model, Malloy, Runtime, AtomicFieldType, ConnectionRuntime, SingleConnectionRuntime, EmptyURLReader, InMemoryURLReader, FixedConnectionMap, MalloyError, JoinRelationship, SourceRelationship, DateTimeframe, TimestampTimeframe, PreparedResult, Result, QueryMaterializer, CSVWriter, JSONWriter, Parse, DataWriter, Explore, } from './malloy';
 export type { PreparedQuery, Field, AtomicField, ExploreField, QueryField, SortableField, DataArray, DataRecord, DataColumn, DataArrayOrRecord, Loggable, ModelMaterializer, DocumentTablePath, DocumentSymbol, ResultJSON, PreparedResultMaterializer, SQLBlockMaterializer, ExploreMaterializer, WriteStream, SerializedExplore, DateField, TimestampField, } from './malloy';
 export type { QueryOptionsReader, RunSQLOptions } from './run_sql_options';
-export type { ModelString, ModelURL, QueryString, QueryURL, URLReader, } from './runtime_types';
+export type { EventStream, ModelString, ModelURL, QueryString, QueryURL, URLReader, } from './runtime_types';
 export type { Connection, ConnectionConfig, ConnectionFactory, ConnectionParameter, ConnectionParameterValue, ConnectionConfigSchema, FetchSchemaOptions, InfoConnection, LookupConnection, PersistSQLResults, PooledConnection, TestableConnection, StreamingConnection, } from './connection/types';
 export { toAsyncGenerator } from './connection_utils';
 export { type TagParse, Tag, type TagDict } from './tags';

package/dist/lang/parse-log.d.ts

@@ -1,4 +1,5 @@
 import { DocumentLocation, FieldValueType } from '../model/malloy_types';
+import { EventStream } from '../runtime_types';
 export type LogSeverity = 'error' | 'warn' | 'debug';
 /**
  * Default severity is "error"
@@ -21,7 +22,9 @@ export interface MessageLogger {
     empty(): boolean;
 }
 export declare class BaseMessageLogger implements MessageLogger {
+    private readonly eventStream;
     private rawLog;
+    constructor(eventStream: EventStream | null);
     getLog(): LogMessage[];
     /**
      * Add a message to the log.

package/dist/lang/parse-log.js

@@ -24,7 +24,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeLogMessage = exports.MESSAGE_FORMATTERS = exports.BaseMessageLogger = void 0;
 class BaseMessageLogger {
-    constructor() {
+    constructor(eventStream) {
+        this.eventStream = eventStream;
         this.rawLog = [];
     }
     getLog() {
@@ -34,7 +35,13 @@ class BaseMessageLogger {
      * Add a message to the log.
      */
     log(logMsg) {
+        var _a;
         this.rawLog.push(logMsg);
+        (_a = this.eventStream) === null || _a === void 0 ? void 0 : _a.emit(`translation-${logMsg.severity}`, {
+            code: logMsg.code,
+            data: logMsg.data,
+            message: logMsg.message,
+        });
     }
     reset() {
         this.rawLog.length = 0;

package/dist/lang/parse-malloy.d.ts

@@ -1,11 +1,12 @@
 import { ANTLRErrorListener, ParserRuleContext, Token } from 'antlr4ts';
 import { DocumentLocation, DocumentPosition, DocumentRange, DocumentReference, ImportLocation, ModelDef, NamedModelObject, Query, SQLBlockStructDef, StructDef } from '../model/malloy_types';
-import { BaseMessageLogger, LogMessage, LogMessageOptions, MessageCode, MessageLogger, MessageParameterType } from './parse-log';
+import { LogMessage, LogMessageOptions, MessageCode, MessageLogger, MessageParameterType } from './parse-log';
 import { Zone, ZoneData } from './zone';
 import { ReferenceList } from './reference-list';
 import { ASTResponse, CompletionsResponse, DataRequestResponse, ProblemResponse, FatalResponse, FinalResponse, HelpContextResponse, MetadataResponse, ModelDataRequest, NeedURLData, TranslateResponse, ModelAnnotationResponse, TablePathResponse } from './translate-response';
 import { Tag } from '../tags';
 import { MalloyParseInfo } from './malloy-parse-info';
+import { EventStream } from '../runtime_types';
 export type StepResponses = DataRequestResponse | ASTResponse | TranslateResponse | ParseResponse | MetadataResponse;
 /**
  * A Translation is a series of translation steps. Each step can depend
@@ -184,12 +185,13 @@ export declare class MalloyChildTranslator extends MalloyTranslation {
  * no need to call again, the translation is finished or error'd.
  */
 export declare class MalloyTranslator extends MalloyTranslation {
+    private readonly eventStream;
     schemaZone: Zone<StructDef>;
     importZone: Zone<string>;
     sqlQueryZone: Zone<SQLBlockStructDef>;
-    logger: BaseMessageLogger;
+    logger: MessageLogger;
     readonly root: MalloyTranslator;
-    constructor(rootURL: string, importURL?: string | null, preload?: ParseUpdate | null);
+    constructor(rootURL: string, importURL?: string | null, preload?: ParseUpdate | null, eventStream?: EventStream | null);
     update(dd: ParseUpdate): void;
     logError<T extends MessageCode>(code: T, parameters: MessageParameterType<T>, options?: Omit<LogMessageOptions, 'severity'>): T;
 }

package/dist/lang/parse-malloy.js

@@ -806,13 +806,14 @@ exports.MalloyChildTranslator = MalloyChildTranslator;
  * no need to call again, the translation is finished or error'd.
  */
 class MalloyTranslator extends MalloyTranslation {
-    constructor(rootURL, importURL = null, preload = null) {
+    constructor(rootURL, importURL = null, preload = null, eventStream = null) {
         super(rootURL, importURL);
+        this.eventStream = eventStream;
         this.schemaZone = new zone_1.Zone();
         this.importZone = new zone_1.Zone();
         this.sqlQueryZone = new zone_1.Zone();
-        this.logger = new parse_log_1.BaseMessageLogger();
         this.root = this;
+        this.logger = new parse_log_1.BaseMessageLogger(eventStream);
         if (preload) {
             this.update(preload);
         }

package/dist/lang/test/test-translator.d.ts

@@ -6,6 +6,7 @@ import { MalloyChildTranslator, MalloyTranslator } from '../parse-malloy';
 import { DataRequestResponse, TranslateResponse } from '../translate-response';
 import { ExprValue } from '../ast/types/expr-value';
 import { LogSeverity, MessageCode, MessageParameterType } from '../parse-log';
+import { EventStream } from '../../runtime_types';
 export declare function pretty(thing: any): string;
 export declare const aTableDef: StructDef;
 /**
@@ -30,7 +31,7 @@ export declare class TestTranslator extends MalloyTranslator {
     allDialectsEnabled: boolean;
     testRoot?: TestRoot;
     internalModel: ModelDef;
-    constructor(testSrc: string, importBaseURL?: string | null, rootRule?: string, internalModel?: ModelDef);
+    constructor(testSrc: string, importBaseURL?: string | null, eventStream?: EventStream | null, rootRule?: string, internalModel?: ModelDef);
     translate(): TranslateResponse;
     addChild(url: string): void;
     ast(): MalloyElement | undefined;

package/dist/lang/test/test-translator.js

@@ -204,8 +204,8 @@ class TestChildTranslator extends parse_malloy_1.MalloyChildTranslator {
 exports.TestChildTranslator = TestChildTranslator;
 const testURI = 'internal://test/langtests/root.malloy';
 class TestTranslator extends parse_malloy_1.MalloyTranslator {
-    constructor(testSrc, importBaseURL = null, rootRule = 'malloyDocument', internalModel) {
-        super(testURI, importBaseURL);
+    constructor(testSrc, importBaseURL = null, eventStream = null, rootRule = 'malloyDocument', internalModel) {
+        super(testURI, importBaseURL, null, eventStream);
         this.testSrc = testSrc;
         this.allDialectsEnabled = true;
         /*
@@ -387,7 +387,7 @@ exports.TestTranslator = TestTranslator;
 TestTranslator.inspectCompile = false;
 class BetaExpression extends TestTranslator {
     constructor(src) {
-        super(src, null, 'justExpr');
+        super(src, null, null, 'justExpr');
     }
     testFS() {
         const aStruct = this.internalModel.contents['ab'];
@@ -493,7 +493,7 @@ function makeModelFunc(options) {
         return {
             ...ms,
             translator: new TestTranslator(((_a = options.prefix) !== null && _a !== void 0 ? _a : '') +
-                (options.wrap ? options.wrap(ms.code) : ms.code), null, undefined, options === null || options === void 0 ? void 0 : options.model),
+                (options.wrap ? options.wrap(ms.code) : ms.code), null, null, undefined, options === null || options === void 0 ? void 0 : options.model),
         };
     };
 }

package/dist/malloy.d.ts

@@ -2,8 +2,8 @@
 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, QueryToMaterialize, PrepareResultOptions } from './model';
-import { ModelString, ModelURL, QueryString, QueryURL, URLReader } from './runtime_types';
+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 } from './model';
+import { EventStream, ModelString, ModelURL, QueryString, QueryURL, URLReader } from './runtime_types';
 import { Connection, InfoConnection, LookupConnection } from './connection/types';
 import { Tag, TagParse, TagParseSpec, Taggable } from './tags';
 import { Dialect } from './dialect';
@@ -18,15 +18,19 @@ export interface ParseOptions {
     importBaseURL?: URL;
     testEnvironment?: boolean;
 }
+/** Options for how to run the Malloy semantic checker/translator */
 export interface CompileOptions {
     refreshSchemaCache?: boolean | number;
     noThrowOnError?: boolean;
 }
+/** Options given to the Malloy compiler (QueryModel) */
+interface CompileQueryOptions {
+    replaceMaterializedReferences?: boolean;
+    materializedTablePrefix?: string;
+    eventStream?: EventStream;
+}
 export declare class Malloy {
     static get version(): string;
-    private static _log;
-    static get log(): Loggable;
-    static setLogger(log: Loggable): void;
     private static _parse;
     /**
      * Parse a Malloy document by URL.
@@ -35,9 +39,10 @@ export declare class Malloy {
      * @param urlReader Object capable of fetching URL contents.
      * @return A (promise of a) `Parse` result.
      */
-    static parse({ url, urlReader, options, }: {
+    static parse({ url, urlReader, eventStream, options, }: {
         url: URL;
         urlReader: URLReader;
+        eventStream?: EventStream;
         options?: ParseOptions;
     }): Promise<Parse>;
     /**
@@ -47,9 +52,10 @@ export declare class Malloy {
      * @param source The contents of the Malloy document to parse.
      * @return A `Parse` result.
      */
-    static parse({ source, url, options, }: {
+    static parse({ source, url, eventStream, options, }: {
         url?: URL;
         source: string;
+        eventStream?: EventStream;
         options?: ParseOptions;
     }): Parse;
     /**
@@ -61,13 +67,14 @@ 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, replaceMaterializedReferences, materializedTablePrefix, }: {
+    static compile({ urlReader, connections, parse, model, refreshSchemaCache, noThrowOnError, eventStream, replaceMaterializedReferences, materializedTablePrefix, }: {
         urlReader: URLReader;
         connections: LookupConnection<InfoConnection>;
         parse: Parse;
         model?: Model;
-    } & CompileOptions & PrepareResultOptions): Promise<Model>;
-    static compileSQLBlock(partialModel: ModelDef | undefined, toCompile: SQLBlockSource, options?: PrepareResultOptions): SQLBlock;
+        replaceMaterializedReferences?: boolean;
+    } & CompileOptions & CompileQueryOptions): Promise<Model>;
+    static compileSQLBlock(partialModel: ModelDef | undefined, toCompile: SQLBlockSource, options?: CompileQueryOptions): SQLBlock;
     /**
      * Run a fully-prepared query.
      *
@@ -263,7 +270,13 @@ export declare class PreparedQuery implements Taggable {
      * @return A fully-prepared query (which contains the generated SQL).
      */
     get preparedResult(): PreparedResult;
-    getPreparedResult(options?: PrepareResultOptions): PreparedResult;
+    /**
+     * Generate the SQL for this query.
+     *
+     * @return A fully-prepared query (which contains the generated SQL).
+     * @param options.eventStream An event stream to use when compiling the SQL
+     */
+    getPreparedResult(options?: CompileQueryOptions): PreparedResult;
     get dialect(): string;
     /**
      * Get the flattened version of a query -- one that does not have a `pipeHead`.
@@ -736,11 +749,12 @@ export declare class Runtime {
     isTestRuntime: boolean;
     private _urlReader;
     private _connections;
+    private _eventStream;
     constructor(runtime: LookupConnection<Connection> & URLReader);
-    constructor(urls: URLReader, connections: LookupConnection<Connection>);
-    constructor(urls: URLReader, connection: Connection);
-    constructor(connection: Connection);
-    constructor(connections: LookupConnection<Connection>);
+    constructor(urls: URLReader, connections: LookupConnection<Connection>, eventStream?: EventStream);
+    constructor(urls: URLReader, connection: Connection, eventStream?: EventStream);
+    constructor(connection: Connection, eventStream?: EventStream);
+    constructor(connections: LookupConnection<Connection>, eventStream?: EventStream);
     /**
      * @return The `URLReader` for this runtime instance.
      */
@@ -749,6 +763,10 @@ export declare class Runtime {
      * @return The `LookupConnection<Connection>` for this runtime instance.
      */
     get connections(): LookupConnection<Connection>;
+    /**
+     * @return The `EventStream` for this runtime instance.
+     */
+    get eventStream(): EventStream | undefined;
     /**
      * Load a Malloy model by URL or contents.
      *
@@ -756,8 +774,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 & PrepareResultOptions): ModelMaterializer;
-    _loadModelFromModelDef(modelDef: ModelDef, options?: PrepareResultOptions): ModelMaterializer;
+    loadModel(source: ModelURL | ModelString, options?: ParseOptions & CompileOptions & CompileQueryOptions): ModelMaterializer;
+    _loadModelFromModelDef(modelDef: ModelDef, options?: CompileQueryOptions): ModelMaterializer;
     /**
      * Load a Malloy query by URL or contents.
      *
@@ -765,7 +783,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 & PrepareResultOptions): QueryMaterializer;
+    loadQuery(query: QueryURL | QueryString, options?: ParseOptions & CompileOptions & CompileQueryOptions): 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.
@@ -775,7 +793,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 & PrepareResultOptions): QueryMaterializer;
+    loadQueryByIndex(model: ModelURL | ModelString, index: number, options?: ParseOptions & CompileOptions & CompileQueryOptions): 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.
@@ -785,7 +803,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 & PrepareResultOptions): QueryMaterializer;
+    loadQueryByName(model: ModelURL | ModelString, name: string, options?: ParseOptions & CompileOptions & CompileQueryOptions): 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.
@@ -795,7 +813,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 & PrepareResultOptions): SQLBlockMaterializer;
+    loadSQLBlockByName(model: ModelURL | ModelString, name: string, options?: ParseOptions & CompileOptions & CompileQueryOptions): 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 +882,10 @@ export declare class ConnectionRuntime extends Runtime {
 }
 export declare class SingleConnectionRuntime<T extends Connection = Connection> extends Runtime {
     readonly connection: T;
-    constructor(urls: URLReader, connection: T);
+    constructor(urlReader: URLReader, connection: T);
     constructor(connection: T);
+    constructor(connection: T, eventStream: EventStream);
+    constructor(urlReader: URLReader, connection: T, eventStream: EventStream);
     get supportsNesting(): boolean;
     quote(column: string): string;
     get dialect(): Dialect;
@@ -878,10 +898,11 @@ declare class FluentState<T> {
     constructor(runtime: Runtime, materialize: () => Promise<T>);
     protected materialize(): Promise<T>;
     protected rematerialize(): Promise<T>;
-    protected makeQueryMaterializer(materialize: () => Promise<PreparedQuery>, options?: PrepareResultOptions): QueryMaterializer;
-    protected makeExploreMaterializer(materialize: () => Promise<Explore>, options?: PrepareResultOptions): ExploreMaterializer;
+    protected makeQueryMaterializer(materialize: () => Promise<PreparedQuery>, options?: CompileQueryOptions): QueryMaterializer;
+    protected makeExploreMaterializer(materialize: () => Promise<Explore>, options?: CompileQueryOptions): ExploreMaterializer;
     protected makePreparedResultMaterializer(materialize: () => Promise<PreparedResult>): PreparedResultMaterializer;
     protected makeSQLBlockMaterializer(materialize: () => Promise<SQLBlockStructDef>): SQLBlockMaterializer;
+    get eventStream(): EventStream | undefined;
 }
 /**
  * An object representing the task of loading a `Model`, capable of
@@ -890,15 +911,15 @@ declare class FluentState<T> {
  */
 export declare class ModelMaterializer extends FluentState<Model> {
     protected runtime: Runtime;
-    private readonly prepareResultOptions;
-    constructor(runtime: Runtime, materialize: () => Promise<Model>, options?: PrepareResultOptions);
+    private readonly compileQueryOptions;
+    constructor(runtime: Runtime, materialize: () => Promise<Model>, options?: CompileQueryOptions);
     /**
      * 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(options?: PrepareResultOptions): QueryMaterializer;
+    loadFinalQuery(options?: CompileQueryOptions): QueryMaterializer;
     /**
      * Load an unnamed query contained within this loaded `Model` by index.
      *
@@ -906,7 +927,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, options?: PrepareResultOptions): QueryMaterializer;
+    loadQueryByIndex(index: number, options?: CompileQueryOptions): QueryMaterializer;
     /**
      * Load a query contained within this loaded `Model` by its name.
      *
@@ -914,7 +935,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, options?: PrepareResultOptions): QueryMaterializer;
+    loadQueryByName(name: string, options?: CompileQueryOptions): QueryMaterializer;
     /**
      * Load a query against this loaded `Model` by its URL or contents.
      *
@@ -922,7 +943,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 & PrepareResultOptions): QueryMaterializer;
+    loadQuery(query: QueryString | QueryURL, options?: ParseOptions & CompileOptions & CompileQueryOptions): QueryMaterializer;
     /**
      * Extend a Malloy model by URL or contents.
      *
@@ -930,8 +951,8 @@ 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 & PrepareResultOptions): ModelMaterializer;
-    search(sourceName: string, searchTerm: string, limit?: number, searchField?: string | undefined): Promise<SearchIndexResult[] | undefined>;
+    extendModel(query: QueryString | QueryURL, options?: ParseOptions & CompileOptions & CompileQueryOptions): ModelMaterializer;
+    search(sourceName: string, searchTerm: string, limit?: number, searchField?: string | undefined, eventStream?: EventStream): Promise<SearchIndexResult[] | undefined>;
     searchValueMap(sourceName: string, limit?: number, options?: ParseOptions): Promise<SearchValueMapResult[] | undefined>;
     /**
      * Load a SQL Block by name.
@@ -994,7 +1015,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, options?: PrepareResultOptions): QueryMaterializer;
+    _loadQueryFromQueryDef(query: InternalQuery, options?: CompileQueryOptions): QueryMaterializer;
     /**
      * Load an explore contained within this loaded `Model` by name.
      *
@@ -1024,34 +1045,34 @@ export declare class ModelMaterializer extends FluentState<Model> {
  */
 export declare class QueryMaterializer extends FluentState<PreparedQuery> {
     protected runtime: Runtime;
-    private readonly prepareResultOptions;
-    constructor(runtime: Runtime, materialize: () => Promise<PreparedQuery>, options?: PrepareResultOptions);
+    private readonly compileQueryOptions;
+    constructor(runtime: Runtime, materialize: () => Promise<PreparedQuery>, options?: CompileQueryOptions);
     /**
      * Run this loaded `Query`.
      *
      * @return The query results from running this loaded query.
      */
-    run(options?: RunSQLOptions & PrepareResultOptions): Promise<Result>;
-    runStream(options?: RunSQLOptions & PrepareResultOptions): AsyncIterableIterator<DataRecord>;
+    run(options?: RunSQLOptions & CompileQueryOptions): Promise<Result>;
+    runStream(options?: RunSQLOptions & CompileQueryOptions): AsyncIterableIterator<DataRecord>;
     /**
      * Load the prepared result of this loaded query.
      *
      * @return A `PreparedResultMaterializer` capable of materializing the requested
      * prepared query or running it.
      */
-    loadPreparedResult(options?: PrepareResultOptions): PreparedResultMaterializer;
+    loadPreparedResult(options?: CompileQueryOptions): PreparedResultMaterializer;
     /**
      * Materialize the prepared result of this loaded query.
      *
      * @return A promise of the prepared result of this loaded query.
      */
-    getPreparedResult(options?: PrepareResultOptions): Promise<PreparedResult>;
+    getPreparedResult(options?: CompileQueryOptions): Promise<PreparedResult>;
     /**
      * Materialize the SQL of this loaded query.
      *
      * @return A promise of the SQL string.
      */
-    getSQL(options?: PrepareResultOptions): Promise<string>;
+    getSQL(options?: CompileQueryOptions): Promise<string>;
     /**
      * Materialize this loaded query.
      *
@@ -1063,7 +1084,7 @@ export declare class QueryMaterializer extends FluentState<PreparedQuery> {
      *
      * @return The estimated cost of running this loaded query.
      */
-    estimateQueryCost(options?: PrepareResultOptions): Promise<QueryRunStats>;
+    estimateQueryCost(options?: CompileQueryOptions): Promise<QueryRunStats>;
 }
 /**
  * An object representing the task of loading a `PreparedResult`, capable of
@@ -1130,7 +1151,7 @@ export declare class SQLBlockMaterializer extends FluentState<SQLBlockStructDef>
 export declare class ExploreMaterializer extends FluentState<Explore> {
     protected runtime: Runtime;
     private readonly replaceMaterializedReferences;
-    constructor(runtime: Runtime, materialize: () => Promise<Explore>, options?: PrepareResultOptions);
+    constructor(runtime: Runtime, materialize: () => Promise<Explore>, options?: CompileQueryOptions);
     /**
      * Load a query contained within this loaded explore.
      *
@@ -1138,7 +1159,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, options?: PrepareResultOptions): QueryMaterializer;
+    loadQueryByName(name: string, options?: CompileQueryOptions): QueryMaterializer;
     /**
      * Materialize a query contained within this loaded explore.
      *

package/dist/malloy.js

@@ -33,13 +33,7 @@ class Malloy {
     static get version() {
         return '0.0.1';
     }
-    static get log() {
-        return Malloy._log || console;
-    }
-    static setLogger(log) {
-        Malloy._log = log;
-    }
-    static _parse(source, url, options) {
+    static _parse(source, url, eventStream, options) {
         if (url === undefined) {
             url = new URL('internal://internal.malloy');
         }
@@ -49,15 +43,15 @@ class Malloy {
         }
         const translator = new lang_1.MalloyTranslator(url.toString(), importBaseURL.toString(), {
             urls: { [url.toString()]: source },
-        });
+        }, eventStream);
         if (options === null || options === void 0 ? void 0 : options.testEnvironment) {
             translator.allDialectsEnabled = true;
         }
         return new Parse(translator);
     }
-    static parse({ url, urlReader, source, options, }) {
+    static parse({ url, urlReader, source, eventStream, options, }) {
         if (source !== undefined) {
-            return Malloy._parse(source, url, options);
+            return Malloy._parse(source, url, eventStream, options);
         }
         else {
             if (urlReader === undefined) {
@@ -67,7 +61,7 @@ class Malloy {
                 throw new Error('Internal Error: url is required if source not present.');
             }
             return urlReader.readURL(url).then(source => {
-                return Malloy._parse(source, url, options);
+                return Malloy._parse(source, url, eventStream, options);
             });
         }
     }
@@ -80,7 +74,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, replaceMaterializedReferences, materializedTablePrefix, }) {
+    static async compile({ urlReader, connections, parse, model, refreshSchemaCache, noThrowOnError, eventStream, replaceMaterializedReferences, materializedTablePrefix, }) {
         var _a, _b, _c, _d;
         let refreshTimestamp;
         if (refreshSchemaCache) {
@@ -177,7 +171,11 @@ class Malloy {
                     const connectionName = toCompile.connection;
                     try {
                         const conn = await connections.lookupConnection(connectionName);
-                        const expanded = Malloy.compileSQLBlock(result.partialModel, toCompile, { replaceMaterializedReferences, materializedTablePrefix });
+                        const expanded = Malloy.compileSQLBlock(result.partialModel, toCompile, {
+                            replaceMaterializedReferences,
+                            materializedTablePrefix,
+                            eventStream,
+                        });
                         const resolved = await conn.fetchSchemaForSQLBlock(expanded, {
                             refreshTimestamp,
                             modelAnnotation,
@@ -219,7 +217,7 @@ class Malloy {
                     if (!partialModel) {
                         throw new Error('Internal error: Partial model missing when compiling SQL block');
                     }
-                    queryModel = new model_1.QueryModel(partialModel);
+                    queryModel = new model_1.QueryModel(partialModel, options === null || options === void 0 ? void 0 : options.eventStream);
                 }
                 const compiledSql = queryModel.compileQuery(segment, options, false).sql;
                 selectStr += parenAlready ? compiledSql : `(${compiledSql})`;
@@ -526,8 +524,14 @@ class PreparedQuery {
     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 = new model_1.QueryModel(this._modelDef);
+        const queryModel = new model_1.QueryModel(this._modelDef, options === null || options === void 0 ? void 0 : options.eventStream);
         const translatedQuery = queryModel.compileQuery(this._query, options);
         return new PreparedResult({
             ...translatedQuery,
@@ -1560,13 +1564,20 @@ class Runtime {
         this.isTestRuntime = false;
         let urlReader;
         let connections;
+        let eventStream;
         for (const arg of args) {
-            if (isURLReader(arg)) {
+            if (arg === undefined) {
+                continue;
+            }
+            else if (isURLReader(arg)) {
                 urlReader = arg;
             }
             else if (isLookupConnection(arg)) {
                 connections = arg;
             }
+            else if (isEventStream(arg)) {
+                eventStream = arg;
+            }
             else {
                 connections = {
                     lookupConnection: () => Promise.resolve(arg),
@@ -1581,6 +1592,7 @@ class Runtime {
         }
         this._urlReader = urlReader;
         this._connections = connections;
+        this._eventStream = eventStream;
     }
     /**
      * @return The `URLReader` for this runtime instance.
@@ -1594,6 +1606,12 @@ class Runtime {
     get connections() {
         return this._connections;
     }
+    /**
+     * @return The `EventStream` for this runtime instance.
+     */
+    get eventStream() {
+        return this._eventStream;
+    }
     /**
      * Load a Malloy model by URL or contents.
      *
@@ -1616,10 +1634,12 @@ class Runtime {
                 ? await Malloy.parse({
                     url: source,
                     urlReader: this.urlReader,
+                    eventStream: this.eventStream,
                     options,
                 })
                 : Malloy.parse({
                     source,
+                    eventStream: this.eventStream,
                     options,
                 });
             return Malloy.compile({
@@ -1628,6 +1648,7 @@ class Runtime {
                 parse,
                 refreshSchemaCache,
                 noThrowOnError,
+                eventStream: this.eventStream,
                 replaceMaterializedReferences: options === null || options === void 0 ? void 0 : options.replaceMaterializedReferences,
                 materializedTablePrefix: options === null || options === void 0 ? void 0 : options.materializedTablePrefix,
             });
@@ -1781,17 +1802,26 @@ class ConnectionRuntime extends Runtime {
 }
 exports.ConnectionRuntime = ConnectionRuntime;
 class SingleConnectionRuntime extends Runtime {
-    constructor(urlsOrConnections, maybeConnections) {
-        if (maybeConnections === undefined) {
-            const connection = urlsOrConnections;
-            super(connection);
-            this.connection = connection;
+    constructor(...params) {
+        let urlReader;
+        let connection;
+        let eventStream;
+        for (const param of params) {
+            if (isURLReader(param)) {
+                urlReader = param;
+            }
+            if (isConnection(param)) {
+                connection = param;
+            }
+            if (isEventStream(param)) {
+                eventStream = param;
+            }
         }
-        else {
-            const connection = maybeConnections;
-            super(urlsOrConnections, connection);
-            this.connection = connection;
+        if (connection === undefined) {
+            throw new Error('Expected connection to be passed into SingleConnectionRuntime');
         }
+        super(urlReader, connection, eventStream);
+        this.connection = connection;
     }
     get supportsNesting() {
         return (0, dialect_1.getDialect)(this.connection.dialectName).supportsNesting;
@@ -1835,6 +1865,9 @@ class FluentState {
     makeSQLBlockMaterializer(materialize) {
         return new SQLBlockMaterializer(this.runtime, materialize);
     }
+    get eventStream() {
+        return this.runtime.eventStream;
+    }
 }
 /**
  * An object representing the task of loading a `Model`, capable of
@@ -1845,7 +1878,7 @@ class ModelMaterializer extends FluentState {
     constructor(runtime, materialize, options) {
         super(runtime, materialize);
         this.runtime = runtime;
-        this.prepareResultOptions = options;
+        this.compileQueryOptions = options;
     }
     /**
      * Load the final (unnamed) Malloy query contained within this loaded `Model`.
@@ -1857,7 +1890,7 @@ class ModelMaterializer extends FluentState {
         return this.makeQueryMaterializer(async () => {
             return (await this.materialize()).getPreparedQuery();
         }, {
-            ...this.prepareResultOptions,
+            ...this.compileQueryOptions,
             ...options,
         });
     }
@@ -1872,7 +1905,7 @@ class ModelMaterializer extends FluentState {
         return this.makeQueryMaterializer(async () => {
             return (await this.materialize()).getPreparedQueryByIndex(index);
         }, {
-            ...this.prepareResultOptions,
+            ...this.compileQueryOptions,
             ...options,
         });
     }
@@ -1887,7 +1920,7 @@ class ModelMaterializer extends FluentState {
         return this.makeQueryMaterializer(async () => {
             return (await this.materialize()).getPreparedQueryByName(name);
         }, {
-            ...this.prepareResultOptions,
+            ...this.compileQueryOptions,
             ...options,
         });
     }
@@ -1929,7 +1962,7 @@ class ModelMaterializer extends FluentState {
                 model,
                 refreshSchemaCache,
                 noThrowOnError,
-                ...this.prepareResultOptions,
+                ...this.compileQueryOptions,
             });
             return queryModel.preparedQuery;
         });
@@ -1971,14 +2004,14 @@ 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,
-                ...this.prepareResultOptions,
+                ...this.compileQueryOptions,
             });
             return queryModel;
         }, options);
     }
-    async search(sourceName, searchTerm, limit = 1000, searchField = undefined) {
+    async search(sourceName, searchTerm, limit = 1000, searchField = undefined, eventStream) {
         const model = await this.materialize();
-        const queryModel = new model_1.QueryModel(model._modelDef);
+        const queryModel = new model_1.QueryModel(model._modelDef, eventStream);
         const schema = model.getExploreByName(sourceName).structDef;
         if (schema.structRelationship.type !== 'basetable') {
             throw new Error("Expected schema's structRelationship type to be 'basetable'.");
@@ -2107,7 +2140,7 @@ class ModelMaterializer extends FluentState {
             const model = await this.materialize();
             return new PreparedQuery(query, model._modelDef, model.problems);
         }, {
-            ...this.prepareResultOptions,
+            ...this.compileQueryOptions,
             ...options,
         });
     }
@@ -2121,7 +2154,7 @@ class ModelMaterializer extends FluentState {
     loadExploreByName(name) {
         return this.makeExploreMaterializer(async () => {
             return (await this.materialize()).getExploreByName(name);
-        }, this.prepareResultOptions);
+        }, this.compileQueryOptions);
     }
     /**
      * Materialize an explore contained within this loaded `Model` by its name.
@@ -2151,7 +2184,7 @@ class QueryMaterializer extends FluentState {
     constructor(runtime, materialize, options) {
         super(runtime, materialize);
         this.runtime = runtime;
-        this.prepareResultOptions = options;
+        this.compileQueryOptions = options;
     }
     /**
      * Run this loaded `Query`.
@@ -2160,18 +2193,12 @@ class QueryMaterializer extends FluentState {
      */
     async run(options) {
         const connections = this.runtime.connections;
-        const preparedResult = await this.getPreparedResult({
-            ...this.prepareResultOptions,
-            ...options,
-        });
+        const preparedResult = await this.getPreparedResult(options);
         const finalOptions = runSQLOptionsWithAnnotations(preparedResult, options);
         return Malloy.run({ connections, preparedResult, options: finalOptions });
     }
     async *runStream(options) {
-        const preparedResult = await this.getPreparedResult({
-            ...this.prepareResultOptions,
-            ...options,
-        });
+        const preparedResult = await this.getPreparedResult(options);
         const connections = this.runtime.connections;
         const finalOptions = runSQLOptionsWithAnnotations(preparedResult, options);
         const stream = Malloy.runStream({
@@ -2192,7 +2219,8 @@ class QueryMaterializer extends FluentState {
     loadPreparedResult(options) {
         return this.makePreparedResultMaterializer(async () => {
             return (await this.materialize()).getPreparedResult({
-                ...this.prepareResultOptions,
+                eventStream: this.eventStream,
+                ...this.compileQueryOptions,
                 ...options,
             });
         });
@@ -2203,10 +2231,7 @@ class QueryMaterializer extends FluentState {
      * @return A promise of the prepared result of this loaded query.
      */
     getPreparedResult(options) {
-        return this.loadPreparedResult({
-            ...this.prepareResultOptions,
-            ...options,
-        }).getPreparedResult();
+        return this.loadPreparedResult(options).getPreparedResult();
     }
     /**
      * Materialize the SQL of this loaded query.
@@ -2214,10 +2239,7 @@ class QueryMaterializer extends FluentState {
      * @return A promise of the SQL string.
      */
     async getSQL(options) {
-        return (await this.getPreparedResult({
-            ...this.prepareResultOptions,
-            ...options,
-        })).sql;
+        return (await this.getPreparedResult(options)).sql;
     }
     /**
      * Materialize this loaded query.
@@ -2234,10 +2256,7 @@ class QueryMaterializer extends FluentState {
      */
     async estimateQueryCost(options) {
         const connections = this.runtime.connections;
-        const preparedResult = await this.getPreparedResult({
-            ...this.prepareResultOptions,
-            ...options,
-        });
+        const preparedResult = await this.getPreparedResult(options);
         return Malloy.estimateQueryCost({ connections, preparedResult });
     }
 }
@@ -2924,6 +2943,12 @@ function isURLReader(thing) {
 function isLookupConnection(thing) {
     return 'lookupConnection' in thing;
 }
+function isEventStream(thing) {
+    return 'emit' in thing;
+}
+function isConnection(thing) {
+    return 'runSQL' in thing;
+}
 class DataWriter {
     constructor(stream) {
         this.stream = stream;

package/dist/model/malloy_query.d.ts

@@ -3,6 +3,7 @@ import { AggregateFunctionType, Annotation, CompiledQuery, Expr, FieldDef, Filte
 import { Connection } from '../connection/types';
 import { AndChain } from './utils';
 import { QueryInfo } from '../dialect/dialect';
+import { EventStream } from '../runtime_types';
 interface TurtleDefPlus extends TurtleDef, Filtered {
 }
 /** Parent from QueryStruct. */
@@ -303,6 +304,7 @@ declare class QueryStruct extends QueryNode {
     connectionName: string;
     readonly stacki: string;
     constructor(fieldDef: StructDef, sourceArguments: Record<string, Argument> | undefined, parent: ParentQueryStruct | ParentQueryModel, prepareResultOptions?: PrepareResultOptions | undefined);
+    maybeEmitParameterizedSourceUsage(): void;
     resolveParentParameterReferences(param: Parameter): Parameter;
     private _arguments;
     arguments(): Record<string, Argument>;
@@ -324,6 +326,7 @@ declare class QueryStruct extends QueryNode {
      */
     resolveQueryFields(): void;
     getModel(): QueryModel;
+    get eventStream(): EventStream | undefined;
     setParent(parent: ParentQueryStruct | ParentQueryModel): void;
     /** makes a new queryable field object from a fieldDef */
     makeQueryField(field: FieldDef, referenceId?: string): QueryField;
@@ -353,10 +356,11 @@ interface QueryResults {
 }
 /** start here */
 export declare class QueryModel {
+    readonly eventStream?: EventStream | undefined;
     dialect: Dialect;
     modelDef: ModelDef | undefined;
     structs: Map<string, QueryStruct>;
-    constructor(modelDef: ModelDef | undefined);
+    constructor(modelDef: ModelDef | undefined, eventStream?: EventStream | undefined);
     loadModelFromDef(modelDef: ModelDef): void;
     getStructByName(name: string): QueryStruct;
     getStructFromRef(structRef: StructRef, sourceArguments: Record<string, Argument> | undefined, prepareResultOptions?: PrepareResultOptions): QueryStruct;

package/dist/model/malloy_query.js

@@ -475,7 +475,9 @@ class QueryField extends QueryNode {
         throw new Error('Unexpanded spread encountered during SQL generation');
     }
     generateParameterFragment(resultSet, context, expr, state) {
+        var _a;
         const name = expr.path[0];
+        (_a = context.eventStream) === null || _a === void 0 ? void 0 : _a.emit('source-argument-compiled', { name });
         const argument = context.arguments()[name];
         if (argument.value) {
             return this.exprToSQL(resultSet, context, argument.value, state);
@@ -2002,8 +2004,13 @@ class QueryQuery extends QueryField {
         return outputStruct;
     }
     generateSQLJoinBlock(stageWriter, ji) {
+        var _a;
         let s = '';
         const qs = ji.queryStruct;
+        (_a = qs.eventStream) === null || _a === void 0 ? void 0 : _a.emit('join-used', {
+            name: qs.fieldDef.as,
+        });
+        qs.maybeEmitParameterizedSourceUsage();
         const structRelationship = qs.fieldDef.structRelationship;
         let structSQL = qs.structSourceSQL(stageWriter);
         if ((0, malloy_types_1.isJoinOn)(structRelationship)) {
@@ -2699,6 +2706,7 @@ class QueryQuery extends QueryField {
         return ret;
     }
     generateSQLFromPipeline(stageWriter) {
+        this.parent.maybeEmitParameterizedSourceUsage();
         this.prepare(stageWriter);
         let lastStageName = this.generateSQL(stageWriter);
         let outputStruct = this.getResultStructDef();
@@ -3006,6 +3014,18 @@ class QueryStruct extends QueryNode {
         this.dialect = (0, dialect_1.getDialect)(this.fieldDef.dialect);
         this.addFieldsFromFieldList(this.fieldDef.fields);
     }
+    maybeEmitParameterizedSourceUsage() {
+        var _a;
+        const paramsAndArgs = {
+            ...this.fieldDef.parameters,
+            ...this.fieldDef.arguments,
+        };
+        if (Object.values(paramsAndArgs).length === 0)
+            return;
+        (_a = this.eventStream) === null || _a === void 0 ? void 0 : _a.emit('parameterized-source-compiled', {
+            parameters: paramsAndArgs,
+        });
+    }
     resolveParentParameterReferences(param) {
         return {
             ...param,
@@ -3223,6 +3243,9 @@ class QueryStruct extends QueryNode {
             return this.parent.getModel();
         }
     }
+    get eventStream() {
+        return this.getModel().eventStream;
+    }
     setParent(parent) {
         if ('struct' in parent) {
             this.parent = parent.struct;
@@ -3414,7 +3437,8 @@ class QueryStruct extends QueryNode {
 // const exploreSearchSQLMap = new Map<string, string>();
 /** start here */
 class QueryModel {
-    constructor(modelDef) {
+    constructor(modelDef, eventStream) {
+        this.eventStream = eventStream;
         this.dialect = new standardsql_1.StandardSQLDialect();
         // dialect: Dialect = new PostgresDialect();
         this.modelDef = undefined;

package/dist/runtime_types.d.ts

@@ -26,3 +26,6 @@ export interface URLReader {
      */
     readURL: (url: URL) => Promise<string>;
 }
+export interface EventStream {
+    emit(id: string, data: any): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/malloy",
-  "version": "0.0.194",
+  "version": "0.0.195-dev241003204819",
   "license": "MIT",
   "exports": {
     ".": "./dist/index.js",