@malloydata/malloy 0.0.2 → 0.0.3

package/README.md

@@ -9,17 +9,16 @@ This package facilitates building the Malloy language - or the usage of data mod
 ## Show me an example!
 
 ```
-import { Runtime } from "@malloydata/malloy";
-import { DuckDBConnection } from "@malloydata/db-duckdb";
-
-const connection = new DuckDBConnection("duckdb-example");
-const runtime = new Runtime(files, connection);
-
-runtime.loadModel("source: flights is table('duckdb:data/flights.parquet')")
-
-const runner = runtime.loadQuery("query: flights->{group_by: flight_num}")
-runner.run() // <- executes query, returns JSON of results
-
+const malloy = require("@malloydata/malloy")
+const bigquery = require("@malloydata/db-bigquery")
+
+const connection = new bigquery.BigQueryConnection("bigquery");
+const runtime = new malloy.SingleConnectionRuntime(connection);
+const model = runtime.loadModel("source: airports is table('malloytest.airports')")
+const runner = model.loadQuery("query: airports->{aggregate: airport_count is count()}")
+runner.run().then((result) => {
+    console.log(result.data.value) // [ { airport_count: 19793 } ]
+})
 ```
 
 Note: These APIs are still in beta and subject to change.
@@ -37,3 +36,5 @@ In practice, much of this loop is handled by various database plugins:
 ## Do you have any examples?
 
 You can find a (very) simple example of writing a CLI for executing Malloy queries [here](https://github.com/looker-open-source/malloy/tree/main/demo/malloy-demo-bq-cli)
+
+A more realistic and complex use case - we use these libraries to power our VSCode Extension. Some examples can be found [here](https://github.com/looker-open-source/malloy/tree/main/vscode-extension/src/extension/commands)

package/dist/dialect/duckdb.d.ts

@@ -34,7 +34,7 @@ export declare class DuckDBDialect extends Dialect {
     sqlSelectAliasAsStruct(alias: string, physicalFieldNames: string[]): string;
     sqlMaybeQuoteIdentifier(identifier: string): string;
     sqlCreateTableAsSelect(_tableName: string, _sql: string): string;
-    getFunctionInfo(_functionName: string): FunctionInfo | undefined;
+    getFunctionInfo(functionName: string): FunctionInfo | undefined;
     sqlMeasureTime(from: TimeValue, to: TimeValue, units: string): Expr;
     sqlNow(): Expr;
     sqlTrunc(sqlTime: TimeValue, units: TimestampUnit): Expr;

package/dist/dialect/duckdb.js

@@ -109,8 +109,6 @@ const inSeconds = {
     second: 1,
     minute: 60,
     hour: 3600,
-    day: 86400,
-    week: 604800,
 };
 class DuckDBDialect extends dialect_1.Dialect {
     constructor() {
@@ -125,7 +123,9 @@ class DuckDBDialect extends dialect_1.Dialect {
         this.defaultSampling = { rows: 50000 };
         this.supportUnnestArrayAgg = true;
         this.supportsCTEinCoorelatedSubQueries = true;
-        this.functionInfo = {};
+        this.functionInfo = {
+            concat: { returnType: "string" },
+        };
     }
     // hack until they support temporary macros.
     get udfPrefix() {
@@ -230,8 +230,8 @@ class DuckDBDialect extends dialect_1.Dialect {
     sqlCreateTableAsSelect(_tableName, _sql) {
         throw new Error("Not implemented Yet");
     }
-    getFunctionInfo(_functionName) {
-        return undefined;
+    getFunctionInfo(functionName) {
+        return this.functionInfo[functionName];
     }
     sqlMeasureTime(from, to, units) {
         let lVal = from.value;
@@ -242,21 +242,20 @@ class DuckDBDialect extends dialect_1.Dialect {
             const duration = (0, model_1.mkExpr) `(${rVal} - ${lVal})`;
             return units == "second"
                 ? duration
-                : (0, model_1.mkExpr) `TRUNC(${duration}/${inSeconds[units].toString()})`;
+                : (0, model_1.mkExpr) `FLOOR(${duration}/${inSeconds[units].toString()})`;
         }
-        const yearDiff = (0, model_1.mkExpr) `TRUNC(EXTRACT(YEAR FROM ${rVal}) - EXTRACT(YEAR FROM ${lVal}))`;
-        if (units == "year") {
-            return yearDiff;
+        if (from.valueType != "date") {
+            lVal = (0, model_1.mkExpr) `CAST((${lVal}) AS DATE)`;
         }
-        if (units == "month") {
-            const monthDiff = (0, model_1.mkExpr) `TRUNC(EXTRACT(MONTH FROM ${rVal}) - EXTRACT(MONTH FROM ${lVal}))`;
-            return (0, model_1.mkExpr) `${yearDiff} * 12 + ${monthDiff}`;
+        if (to.valueType != "date") {
+            rVal = (0, model_1.mkExpr) `CAST((${rVal}) AS DATE)`;
         }
-        if (units == "quarter") {
-            const qDiff = (0, model_1.mkExpr) `TRUNC(EXTRACT(QUARTER FROM ${rVal}) - EXTRACT(QUARTER FROM ${lVal}))`;
-            return (0, model_1.mkExpr) `${yearDiff} * 4 + ${qDiff}`;
+        if (units == "week") {
+            // DuckDB's weeks start on Monday, but Malloy's weeks start on Sunday
+            lVal = (0, model_1.mkExpr) `(${lVal} + INTERVAL 1 DAY)`;
+            rVal = (0, model_1.mkExpr) `(${rVal} + INTERVAL 1 DAY)`;
         }
-        throw new Error(`Unknown or unhandled postgres time unit: ${units}`);
+        return (0, model_1.mkExpr) `DATE_DIFF('${units}', ${lVal}, ${rVal})`;
     }
     sqlNow() {
         return (0, model_1.mkExpr) `CURRENT_TIMESTAMP`;
@@ -265,10 +264,10 @@ class DuckDBDialect extends dialect_1.Dialect {
         // adjusting for monday/sunday weeks
         const week = units == "week";
         const truncThis = week
-            ? (0, model_1.mkExpr) `${sqlTime.value}+interval'1'day`
+            ? (0, model_1.mkExpr) `${sqlTime.value} + INTERVAL 1 DAY`
             : sqlTime.value;
         const trunced = (0, model_1.mkExpr) `DATE_TRUNC('${units}', ${truncThis})`;
-        return week ? (0, model_1.mkExpr) `(${trunced}-interval'1'day)` : trunced;
+        return week ? (0, model_1.mkExpr) `(${trunced} - INTERVAL 1 DAY)` : trunced;
     }
     sqlExtract(from, units) {
         const pgUnits = pgExtractionMap[units] || units;
@@ -284,8 +283,8 @@ class DuckDBDialect extends dialect_1.Dialect {
             timeframe = "day";
             n = (0, model_1.mkExpr) `${n}*7`;
         }
-        const interval = (0, model_1.mkExpr) `INTERVAL ${n} ${timeframe}`;
-        return (0, model_1.mkExpr) `((${expr.value})${op}${interval})`;
+        const interval = (0, model_1.mkExpr) `INTERVAL (${n}) ${timeframe}`;
+        return (0, model_1.mkExpr) `((${expr.value})) ${op} ${interval}`;
     }
     sqlCast(cast) {
         if (cast.dstType !== cast.srcType) {
@@ -299,7 +298,7 @@ class DuckDBDialect extends dialect_1.Dialect {
     }
     sqlLiteralTime(timeString, type, _timezone) {
         if (type == "date") {
-            return `DATE('${timeString}')`;
+            return `DATE '${timeString}'`;
         }
         else if (type == "timestamp") {
             return `TIMESTAMP '${timeString}'`;
@@ -308,24 +307,23 @@ class DuckDBDialect extends dialect_1.Dialect {
             throw new Error(`Unknown Literal time format ${type}`);
         }
     }
-    // sqlSumDistinct(key: string, value: string): string {
-    //   // return `sum_distinct(list({key:${key}, val: ${value}}))`;
-    //   return `(
-    //     fail -- force the query for fail until the bug is fixed.
-    //     SELECT sum(a.val) as value
-    //     FROM (
-    //       SELECT UNNEST(list(distinct {key:${key}, val: ${value}})) a
-    //     )
-    //   )`;
-    // }
     sqlSumDistinct(key, value) {
-        const _factor = 32;
-        const precision = 0.000001;
-        const keySQL = `md5_number_lower(${key}::varchar)::int128`;
-        return `
-    (SUM(DISTINCT ${keySQL} + FLOOR(IFNULL(${value},0)/${precision})::int128) -  SUM(DISTINCT ${keySQL}))*${precision}
-    `;
+        // return `sum_distinct(list({key:${key}, val: ${value}}))`;
+        return `(
+      SELECT sum(a.val) as value
+      FROM (
+        SELECT UNNEST(list(distinct {key:${key}, val: ${value}})) a
+      )
+    )`;
     }
+    // sqlSumDistinct(key: string, value: string): string {
+    //   const _factor = 32;
+    //   const precision = 0.000001;
+    //   const keySQL = `md5_number_lower(${key}::varchar)::int128`;
+    //   return `
+    //   (SUM(DISTINCT ${keySQL} + FLOOR(IFNULL(${value},0)/${precision})::int128) -  SUM(DISTINCT ${keySQL}))*${precision}
+    //   `;
+    // }
     // default duckdb to sampling 50K rows.
     sqlSampleTable(tableSQL, sample) {
         if (sample !== undefined) {

package/dist/dialect/postgres.d.ts

@@ -41,7 +41,7 @@ export declare class PostgresDialect extends Dialect {
     sqlCast(cast: TypecastFragment): Expr;
     sqlRegexpMatch(expr: Expr, regexp: string): Expr;
     sqlLiteralTime(timeString: string, type: TimeFieldType, _timezone: string): string;
-    getFunctionInfo(_functionName: string): FunctionInfo | undefined;
+    getFunctionInfo(functionName: string): FunctionInfo | undefined;
     sqlMeasureTime(from: TimeValue, to: TimeValue, units: string): Expr;
     sqlSumDistinct(key: string, value: string): string;
     sqlSampleTable(tableSQL: string, sample: Sampling | undefined): string;

package/dist/dialect/postgres.js

@@ -37,8 +37,6 @@ const inSeconds = {
     second: 1,
     minute: 60,
     hour: 3600,
-    day: 86400,
-    week: 604800,
 };
 class PostgresDialect extends dialect_1.Dialect {
     constructor() {
@@ -54,7 +52,9 @@ class PostgresDialect extends dialect_1.Dialect {
         this.defaultSampling = { rows: 50000 };
         this.supportUnnestArrayAgg = true;
         this.supportsCTEinCoorelatedSubQueries = true;
-        this.functionInfo = {};
+        this.functionInfo = {
+            concat: { returnType: "string" },
+        };
     }
     quoteTablePath(tablePath) {
         return tablePath
@@ -249,8 +249,8 @@ class PostgresDialect extends dialect_1.Dialect {
             throw new Error(`Unknown Literal time format ${type}`);
         }
     }
-    getFunctionInfo(_functionName) {
-        return undefined;
+    getFunctionInfo(functionName) {
+        return this.functionInfo[functionName];
     }
     sqlMeasureTime(from, to, units) {
         let lVal = from.value;
@@ -263,16 +263,23 @@ class PostgresDialect extends dialect_1.Dialect {
                 ? duration
                 : (0, model_1.mkExpr) `TRUNC(${duration}/${inSeconds[units].toString()})`;
         }
-        const yearDiff = (0, model_1.mkExpr) `TRUNC(EXTRACT(YEAR FROM ${rVal}) - EXTRACT(YEAR FROM ${lVal}))`;
+        if (units === "day") {
+            return (0, model_1.mkExpr) `${rVal}::date - ${lVal}::date`;
+        }
+        const yearDiff = (0, model_1.mkExpr) `(DATE_PART('year', ${rVal}) - DATE_PART('year', ${lVal}))`;
         if (units == "year") {
             return yearDiff;
         }
+        if (units == "week") {
+            const dayDiffForWeekStart = (0, model_1.mkExpr) `(DATE_TRUNC('week', ${rVal} + '1 day'::interval)::date - DATE_TRUNC('week', ${lVal} + '1 day'::interval)::date)`;
+            return (0, model_1.mkExpr) `${dayDiffForWeekStart} / 7`;
+        }
         if (units == "month") {
-            const monthDiff = (0, model_1.mkExpr) `TRUNC(EXTRACT(MONTH FROM ${rVal}) - EXTRACT(MONTH FROM ${lVal}))`;
+            const monthDiff = (0, model_1.mkExpr) `DATE_PART('month', ${rVal}) - DATE_PART('month', ${lVal})`;
             return (0, model_1.mkExpr) `${yearDiff} * 12 + ${monthDiff}`;
         }
         if (units == "quarter") {
-            const qDiff = (0, model_1.mkExpr) `TRUNC(EXTRACT(QUARTER FROM ${rVal}) - EXTRACT(QUARTER FROM ${lVal}))`;
+            const qDiff = (0, model_1.mkExpr) `DATE_PART('quarter', ${rVal}) - DATE_PART('quarter', ${lVal})`;
             return (0, model_1.mkExpr) `${yearDiff} * 4 + ${qDiff}`;
         }
         throw new Error(`Unknown or unhandled postgres time unit: ${units}`);

package/dist/dialect/standardsql.js

@@ -48,6 +48,7 @@ class StandardSQLDialect extends dialect_1.Dialect {
         this.supportsCTEinCoorelatedSubQueries = false;
         this.functionInfo = {
             timestamp_seconds: { returnType: "timestamp" },
+            concat: { returnType: "string" },
         };
         this.keywords = `
   ALL

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export type { QueryDataRow, ModelDef, Fragment, Query, StructDef, NamedStructDefs, MalloyQueryData, AtomicFieldType as AtomicFieldTypeInner, DateUnit, ExtractUnit, TimestampUnit, TimeFieldType, QueryData, FieldTypeDef, Expr, DialectFragment, TimeValue, FilterExpression, SQLBlock, FieldDef, PipeSegment, QueryFieldDef, TurtleDef, SearchValueMapResult, SearchIndexResult, } from "./model";
+export type { QueryDataRow, ModelDef, Fragment, Query, StructDef, StructRelationship, NamedStructDefs, MalloyQueryData, AtomicFieldType as AtomicFieldTypeInner, DateUnit, ExtractUnit, TimestampUnit, TimeFieldType, QueryData, FieldTypeDef, Expr, DialectFragment, TimeValue, FilterExpression, SQLBlock, FieldDef, FilteredAliasedName, PipeSegment, QueryFieldDef, TurtleDef, SearchValueMapResult, SearchIndexResult, } from "./model";
 export { Segment, isFilteredAliasedName, } from "./model";
 export { HighlightType, MalloyTranslator, } from "./lang";
 export type { LogMessage, TranslateResponse } from "./lang";
-export { Malloy, Runtime, AtomicFieldType, ConnectionRuntime, SingleConnectionRuntime, EmptyURLReader, InMemoryURLReader, FixedConnectionMap, MalloyError, JoinRelationship, SourceRelationship, DateTimeframe, TimestampTimeframe, Result, parseTableURL, QueryMaterializer, CSVWriter, JSONWriter, DataWriter, } from "./malloy";
-export type { Explore, Model, PreparedQuery, PreparedResult, Field, AtomicField, ExploreField, QueryField, DataArray, DataRecord, DataColumn, DataArrayOrRecord, ModelMaterializer, DocumentSymbol, DocumentHighlight, ResultJSON, PreparedResultMaterializer, SQLBlockMaterializer, ExploreMaterializer, WriteStream, } from "./malloy";
-export type { URLReader, InfoConnection, LookupConnection, Connection, QueryString, ModelString, QueryURL, ModelURL, PooledConnection, TestableConnection, PersistSQLResults, } from "./runtime_types";
+export { Malloy, Runtime, AtomicFieldType, ConnectionRuntime, SingleConnectionRuntime, EmptyURLReader, InMemoryURLReader, FixedConnectionMap, MalloyError, JoinRelationship, SourceRelationship, DateTimeframe, TimestampTimeframe, Result, parseTableURI, QueryMaterializer, CSVWriter, JSONWriter, DataWriter, } from "./malloy";
+export type { Explore, Model, PreparedQuery, PreparedResult, Field, AtomicField, ExploreField, QueryField, DataArray, DataRecord, DataColumn, DataArrayOrRecord, ModelMaterializer, DocumentSymbol, DocumentHighlight, ResultJSON, RunSQLOptions, PreparedResultMaterializer, SQLBlockMaterializer, ExploreMaterializer, WriteStream, } from "./malloy";
+export type { URLReader, InfoConnection, LookupConnection, Connection, QueryString, ModelString, QueryURL, ModelURL, PooledConnection, TestableConnection, PersistSQLResults, FetchSchemaAndRunSimultaneously, StreamingConnection, FetchSchemaAndRunStreamSimultaneously, } from "./runtime_types";
 export type { Loggable } from "./malloy";
 export { toAsyncGenerator } from "./connection_utils";

package/dist/index.js

@@ -12,7 +12,7 @@
  * GNU General Public License for more details.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toAsyncGenerator = exports.DataWriter = exports.JSONWriter = exports.CSVWriter = exports.QueryMaterializer = exports.parseTableURL = exports.Result = exports.TimestampTimeframe = exports.DateTimeframe = exports.SourceRelationship = exports.JoinRelationship = exports.MalloyError = exports.FixedConnectionMap = exports.InMemoryURLReader = exports.EmptyURLReader = exports.SingleConnectionRuntime = exports.ConnectionRuntime = exports.AtomicFieldType = exports.Runtime = exports.Malloy = exports.MalloyTranslator = exports.HighlightType = exports.isFilteredAliasedName = exports.Segment = void 0;
+exports.toAsyncGenerator = exports.DataWriter = exports.JSONWriter = exports.CSVWriter = exports.QueryMaterializer = exports.parseTableURI = exports.Result = exports.TimestampTimeframe = exports.DateTimeframe = exports.SourceRelationship = exports.JoinRelationship = exports.MalloyError = exports.FixedConnectionMap = exports.InMemoryURLReader = exports.EmptyURLReader = exports.SingleConnectionRuntime = exports.ConnectionRuntime = exports.AtomicFieldType = exports.Runtime = exports.Malloy = exports.MalloyTranslator = exports.HighlightType = exports.isFilteredAliasedName = exports.Segment = void 0;
 var model_1 = require("./model");
 // Used in Composer Demo
 Object.defineProperty(exports, "Segment", { enumerable: true, get: function () { return model_1.Segment; } });
@@ -37,7 +37,7 @@ Object.defineProperty(exports, "SourceRelationship", { enumerable: true, get: fu
 Object.defineProperty(exports, "DateTimeframe", { enumerable: true, get: function () { return malloy_1.DateTimeframe; } });
 Object.defineProperty(exports, "TimestampTimeframe", { enumerable: true, get: function () { return malloy_1.TimestampTimeframe; } });
 Object.defineProperty(exports, "Result", { enumerable: true, get: function () { return malloy_1.Result; } });
-Object.defineProperty(exports, "parseTableURL", { enumerable: true, get: function () { return malloy_1.parseTableURL; } });
+Object.defineProperty(exports, "parseTableURI", { enumerable: true, get: function () { return malloy_1.parseTableURI; } });
 Object.defineProperty(exports, "QueryMaterializer", { enumerable: true, get: function () { return malloy_1.QueryMaterializer; } });
 Object.defineProperty(exports, "CSVWriter", { enumerable: true, get: function () { return malloy_1.CSVWriter; } });
 Object.defineProperty(exports, "JSONWriter", { enumerable: true, get: function () { return malloy_1.JSONWriter; } });

package/dist/lang/ast/apply-expr.js

@@ -43,10 +43,10 @@ function applyBinary(fs, left, op, right) {
         const num = left.getExpression(fs);
         const denom = right.getExpression(fs);
         if (num.dataType != "number") {
-            left.log("Numerator for division mus tbe a number");
+            left.log("Numerator for division must be a number");
         }
         else if (denom.dataType != "number") {
-            right.log("Denominator for division mus tbe a number");
+            right.log("Denominator for division must be a number");
         }
         else {
             const div = {

package/dist/lang/ast/ast-expr.js

@@ -96,20 +96,10 @@ class ConstantFieldSpace {
         this.type = "fieldSpace";
     }
     structDef() {
-        return {
-            type: "struct",
-            name: "empty structdef",
-            structSource: { type: "table" },
-            structRelationship: {
-                type: "basetable",
-                connectionName: "noConnection",
-            },
-            fields: [],
-            dialect: "noDialect",
-        };
+        throw new Error("ConstantFieldSpace cannot generate a structDef");
     }
     emptyStructDef() {
-        return { ...this.structDef(), fields: [] };
+        throw new Error("ConstantFieldSpace cannot generate a structDef");
     }
     lookup(_name) {
         return {

package/dist/lang/ast/ast-main.d.ts

@@ -303,9 +303,9 @@ export declare class WildcardFieldReference extends MalloyElement {
 }
 export declare class OrderBy extends MalloyElement {
     readonly field: number | FieldName;
-    readonly dir?: "asc" | "desc" | undefined;
+    readonly dir?: "desc" | "asc" | undefined;
     elementType: string;
-    constructor(field: number | FieldName, dir?: "asc" | "desc" | undefined);
+    constructor(field: number | FieldName, dir?: "desc" | "asc" | undefined);
     get modelField(): string | number;
     getOrderBy(_fs: FieldSpace): model.OrderBy;
 }

package/dist/lang/ast/ast-main.js

@@ -55,7 +55,7 @@ const theErrorStruct = {
     type: "struct",
     name: "~malformed~",
     dialect: "~malformed~",
-    structSource: { type: "table" },
+    structSource: { type: "table", tablePath: "//undefined_error_table_path" },
     structRelationship: {
         type: "basetable",
         connectionName: "//undefined_error_connection",
@@ -867,6 +867,7 @@ class ExpressionJoin extends Join {
         if (sourceDef.structSource.type === "query") {
             // the name from query does not need to be preserved
             joinStruct.name = this.name.refString;
+            delete joinStruct.as;
         }
         else {
             joinStruct.as = this.name.refString;

package/dist/lang/field-space.d.ts

@@ -48,10 +48,10 @@ export declare type SourceSpec = model.StructDef | FieldSpace;
 /**
  * Based on how things are constructed, the starting field space
  * can either be another field space or an existing structdef.
- * Using a SourceSpace allows a class to accept either one
+ * Using a SpaceSeed allows a class to accept either one
  * and use either version at some future time.
  */
-declare class SourceSpace {
+declare class SpaceSeed {
     readonly sourceSpec: SourceSpec;
     private spaceSpec;
     private asFS?;
@@ -65,7 +65,7 @@ declare class SourceSpace {
  */
 export declare class DynamicSpace extends StaticSpace {
     protected final: model.StructDef | undefined;
-    protected source: SourceSpace;
+    protected source: SpaceSeed;
     outputFS?: QuerySpace;
     completions: (() => void)[];
     private complete;
@@ -86,11 +86,13 @@ export declare class DynamicSpace extends StaticSpace {
     structDef(): model.StructDef;
 }
 /**
- * A namespace for Query operations. The have an input and an
- * output set of fields. The InputSpace is the QueryOperationSpace
- * which is where all expressions are evaluated, and the output
- * space is ResultSpace.
+ * Unlike a source, which is a refinement of a namespace, a query
+ * is creating a new unrelated namespace. The query starts with a
+ * source, which it might modify. This set of fields used to resolve
+ * expressions in the query is called the "input space". There is a
+ * specialized QuerySpace for each type of query operation.
  *
+ * The query output is managed by an instance of ResultSpace.
  */
 export declare class QuerySpace extends DynamicSpace {
     readonly result: ResultSpace;

package/dist/lang/field-space.js

@@ -167,10 +167,10 @@ function isFieldSpace(x) {
 /**
  * Based on how things are constructed, the starting field space
  * can either be another field space or an existing structdef.
- * Using a SourceSpace allows a class to accept either one
+ * Using a SpaceSeed allows a class to accept either one
  * and use either version at some future time.
  */
-class SourceSpace {
+class SpaceSeed {
     constructor(sourceSpec) {
         this.sourceSpec = sourceSpec;
         this.spaceSpec = sourceSpec;
@@ -199,7 +199,7 @@ class SourceSpace {
  */
 class DynamicSpace extends StaticSpace {
     constructor(extending) {
-        const source = new SourceSpace(extending);
+        const source = new SpaceSeed(extending);
         super((0, lodash_1.cloneDeep)(source.structDef));
         this.completions = [];
         this.complete = false;
@@ -365,15 +365,17 @@ class DynamicSpace extends StaticSpace {
 }
 exports.DynamicSpace = DynamicSpace;
 /**
- * A namespace for Query operations. The have an input and an
- * output set of fields. The InputSpace is the QueryOperationSpace
- * which is where all expressions are evaluated, and the output
- * space is ResultSpace.
+ * Unlike a source, which is a refinement of a namespace, a query
+ * is creating a new unrelated namespace. The query starts with a
+ * source, which it might modify. This set of fields used to resolve
+ * expressions in the query is called the "input space". There is a
+ * specialized QuerySpace for each type of query operation.
  *
+ * The query output is managed by an instance of ResultSpace.
  */
 class QuerySpace extends DynamicSpace {
     constructor(input, result) {
-        const inputSpace = new SourceSpace(input);
+        const inputSpace = new SpaceSeed(input);
         super(inputSpace.structDef);
         this.result = result;
         this.extendList = [];