@hypequery/datasets 0.13.6 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -0
- package/dist/agent-catalog.d.ts +97 -0
- package/dist/agent-catalog.d.ts.map +1 -0
- package/dist/agent-catalog.js +79 -0
- package/dist/api.type-test.js +19 -1
- package/dist/catalog.d.ts +17 -6
- package/dist/catalog.d.ts.map +1 -1
- package/dist/catalog.js +18 -1
- package/dist/contract.d.ts +11 -7
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +22 -1
- package/dist/dataset-query.js +1 -1
- package/dist/dataset.d.ts.map +1 -1
- package/dist/dataset.js +19 -2
- package/dist/executor.d.ts +6 -0
- package/dist/executor.d.ts.map +1 -1
- package/dist/executor.js +55 -23
- package/dist/field.d.ts.map +1 -1
- package/dist/field.js +2 -0
- package/dist/index.d.ts +10 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -0
- package/dist/measure.d.ts.map +1 -1
- package/dist/measure.js +4 -0
- package/dist/protocol-adapter.d.ts.map +1 -1
- package/dist/protocol-adapter.js +21 -0
- package/dist/protocol-rehydrate.d.ts +46 -0
- package/dist/protocol-rehydrate.d.ts.map +1 -0
- package/dist/protocol-rehydrate.js +218 -0
- package/dist/publishing/features/dataset-publication.d.ts +10 -0
- package/dist/publishing/features/dataset-publication.d.ts.map +1 -0
- package/dist/publishing/features/dataset-publication.js +34 -0
- package/dist/publishing/node.d.ts +16 -0
- package/dist/publishing/node.d.ts.map +1 -0
- package/dist/publishing/node.js +35 -0
- package/dist/publishing/publisher.d.ts +17 -0
- package/dist/publishing/publisher.d.ts.map +1 -0
- package/dist/publishing/publisher.js +32 -0
- package/dist/publishing/types.d.ts +31 -0
- package/dist/publishing/types.d.ts.map +1 -0
- package/dist/publishing/types.js +1 -0
- package/dist/query-builder-protocol.d.ts +6 -2
- package/dist/query-builder-protocol.d.ts.map +1 -1
- package/dist/semantic-plan.d.ts +3 -1
- package/dist/semantic-plan.d.ts.map +1 -1
- package/dist/semantic-planner.d.ts.map +1 -1
- package/dist/semantic-planner.js +4 -0
- package/dist/semantic-query-schema.d.ts +48 -0
- package/dist/semantic-query-schema.d.ts.map +1 -0
- package/dist/semantic-query-schema.js +218 -0
- package/dist/sql-utils.d.ts +36 -0
- package/dist/sql-utils.d.ts.map +1 -1
- package/dist/sql-utils.js +76 -0
- package/dist/tools.d.ts +5 -0
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js +25 -267
- package/dist/types.d.ts +98 -8
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/agent-catalog-projection.d.ts +78 -0
- package/dist/utils/agent-catalog-projection.d.ts.map +1 -0
- package/dist/utils/agent-catalog-projection.js +179 -0
- package/dist/utils/dataset-cache-policy.d.ts +34 -0
- package/dist/utils/dataset-cache-policy.d.ts.map +1 -0
- package/dist/utils/dataset-cache-policy.js +50 -0
- package/dist/utils/dataset-contract.d.ts +2 -2
- package/dist/utils/dataset-contract.d.ts.map +1 -1
- package/dist/utils/dataset-contract.js +3 -1
- package/dist/utils/dataset-definition-validation.d.ts +35 -0
- package/dist/utils/dataset-definition-validation.d.ts.map +1 -0
- package/dist/utils/dataset-definition-validation.js +215 -0
- package/dist/utils/dataset-metric-ref.d.ts +2 -2
- package/dist/utils/dataset-metric-ref.d.ts.map +1 -1
- package/dist/utils/dataset-metric-ref.js +5 -3
- package/dist/utils/metric-alias.d.ts +4 -0
- package/dist/utils/metric-alias.d.ts.map +1 -0
- package/dist/utils/metric-alias.js +28 -0
- package/dist/utils/protocol-metric-capabilities.d.ts +7 -0
- package/dist/utils/protocol-metric-capabilities.d.ts.map +1 -0
- package/dist/utils/protocol-metric-capabilities.js +57 -0
- package/dist/utils/protocol-rehydrate-filters.d.ts +10 -0
- package/dist/utils/protocol-rehydrate-filters.d.ts.map +1 -0
- package/dist/utils/protocol-rehydrate-filters.js +36 -0
- package/dist/utils/protocol-semantic-metadata.d.ts +5 -0
- package/dist/utils/protocol-semantic-metadata.d.ts.map +1 -0
- package/dist/utils/protocol-semantic-metadata.js +5 -0
- package/dist/utils/published-name.d.ts +3 -0
- package/dist/utils/published-name.d.ts.map +1 -0
- package/dist/utils/published-name.js +7 -0
- package/dist/utils/published-relationships.d.ts +34 -0
- package/dist/utils/published-relationships.d.ts.map +1 -0
- package/dist/utils/published-relationships.js +35 -0
- package/dist/utils/relationship-fields.d.ts +7 -0
- package/dist/utils/relationship-fields.d.ts.map +1 -1
- package/dist/utils/relationship-fields.js +13 -1
- package/dist/utils/result-limits.d.ts +34 -0
- package/dist/utils/result-limits.d.ts.map +1 -0
- package/dist/utils/result-limits.js +40 -0
- package/dist/utils/semantic-metadata-validation.d.ts +4 -0
- package/dist/utils/semantic-metadata-validation.d.ts.map +1 -0
- package/dist/utils/semantic-metadata-validation.js +103 -0
- package/dist/utils/semantic-metadata.d.ts +4 -0
- package/dist/utils/semantic-metadata.d.ts.map +1 -0
- package/dist/utils/semantic-metadata.js +13 -0
- package/dist/utils/semantic-tool.d.ts +5 -0
- package/dist/utils/semantic-tool.d.ts.map +1 -0
- package/dist/utils/semantic-tool.js +29 -0
- package/package.json +5 -4
package/dist/executor.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"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"}
|
package/dist/executor.js
CHANGED
|
@@ -1,9 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
* Semantic dataset client internals.
|
|
3
|
-
*
|
|
4
|
-
* Public callers use `createDatasetClient(...).execute(...)`. The implementation
|
|
5
|
-
* stays database-agnostic via query-builder and backend protocol interfaces.
|
|
6
|
-
*/
|
|
1
|
+
import { protocolMetricCapabilityErrors } from './utils/protocol-metric-capabilities.js';
|
|
7
2
|
import { toQueryBuilderFactory } from './query-builder-protocol.js';
|
|
8
3
|
import { quoteSQLIdentifier, validateSQLIdentifier } from './sql-utils.js';
|
|
9
4
|
import { SUPPORTED_TIME_GRAINS, isSupportedTimeGrain } from './constants.js';
|
|
@@ -18,11 +13,13 @@ import { applyPagination, overfetchLimit } from './utils/pagination.js';
|
|
|
18
13
|
import { serializeSemanticMeasureValues } from './utils/semantic-result-serialization.js';
|
|
19
14
|
import { SemanticQueryCache, } from './cache/semantic-query-cache.js';
|
|
20
15
|
import { buildDatasetQuerySignature, buildMetricQuerySignature, } from './cache/query-signature.js';
|
|
16
|
+
import { resolveResultLimit, withResultLimit } from './utils/result-limits.js';
|
|
17
|
+
import { resolveDatasetCacheRuntime, } from './utils/dataset-cache-policy.js';
|
|
21
18
|
import { isQualifiedField, resolveQualifiedField } from './utils/relationship-fields.js';
|
|
22
19
|
import { validateQualifiedFilter, validateRelationshipTenantRuntime, } from './utils/relationship-validation.js';
|
|
23
20
|
import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './utils/relationship-builder-plan.js';
|
|
24
21
|
function validateQuery(metric, query, context) {
|
|
25
|
-
const errors =
|
|
22
|
+
const errors = protocolMetricCapabilityErrors(metric, query);
|
|
26
23
|
const ref = getMetricRef(metric);
|
|
27
24
|
const ds = ref.dataset;
|
|
28
25
|
const dimensionNames = Object.keys(ds.dimensions);
|
|
@@ -213,7 +210,9 @@ export class MetricQueryEngine {
|
|
|
213
210
|
if (spec.__type === 'derived_metric_spec') {
|
|
214
211
|
// Derived metrics: build CTE via builder, outer query via string, execute via rawQuery
|
|
215
212
|
const { sql, params } = this.buildDerivedSQLViaBuilder(ref, spec, buildQuery, grain, context);
|
|
216
|
-
const rows = await activeBuilderFactory.rawQuery(sql, params
|
|
213
|
+
const rows = await activeBuilderFactory.rawQuery(sql, params, {
|
|
214
|
+
abortSignal: context?.abortSignal,
|
|
215
|
+
});
|
|
217
216
|
const timingMs = Date.now() - start;
|
|
218
217
|
const { data, pagination } = applyPagination(rows, query.limit, query.offset);
|
|
219
218
|
const serializedData = serializeSemanticMeasureValues(data, [ref.name]);
|
|
@@ -231,7 +230,7 @@ export class MetricQueryEngine {
|
|
|
231
230
|
// Base metrics: fully use the builder's execute()
|
|
232
231
|
const builder = this.buildBaseQuery(ref, spec, ref.dataset, buildQuery, grain, context);
|
|
233
232
|
const { sql } = builder.toSQLWithParams();
|
|
234
|
-
const rows = await builder.execute();
|
|
233
|
+
const rows = await builder.execute({ abortSignal: context?.abortSignal });
|
|
235
234
|
const timingMs = Date.now() - start;
|
|
236
235
|
const { data, pagination } = applyPagination(rows, query.limit, query.offset);
|
|
237
236
|
const serializedData = serializeSemanticMeasureValues(data, [ref.name]);
|
|
@@ -372,6 +371,7 @@ export class DatasetClientImpl extends MetricQueryEngine {
|
|
|
372
371
|
backend;
|
|
373
372
|
queryCache;
|
|
374
373
|
cacheEnabledByDefault;
|
|
374
|
+
cacheDefaults;
|
|
375
375
|
defaultCacheScope;
|
|
376
376
|
constructor(options) {
|
|
377
377
|
if (!options.queryBuilder && !options.backend) {
|
|
@@ -391,6 +391,12 @@ export class DatasetClientImpl extends MetricQueryEngine {
|
|
|
391
391
|
this.queryCache = new SemanticQueryCache(options.cache);
|
|
392
392
|
this.cacheEnabledByDefault = (options.cache?.ttlMs ?? 0) > 0;
|
|
393
393
|
this.defaultCacheScope = options.cache?.scope;
|
|
394
|
+
// Kept so a dataset's declared ceiling can clamp the client default too; the
|
|
395
|
+
// cache would otherwise fill a missing TTL from it after clamping has run.
|
|
396
|
+
this.cacheDefaults = {
|
|
397
|
+
ttlMs: options.cache?.ttlMs,
|
|
398
|
+
staleWhileRevalidateMs: options.cache?.staleWhileRevalidateMs,
|
|
399
|
+
};
|
|
394
400
|
}
|
|
395
401
|
getCacheStats() {
|
|
396
402
|
return this.queryCache.getStats();
|
|
@@ -404,7 +410,7 @@ export class DatasetClientImpl extends MetricQueryEngine {
|
|
|
404
410
|
* the common uncached path.
|
|
405
411
|
*/
|
|
406
412
|
isCacheable(context) {
|
|
407
|
-
if (context?.cache === false || context?.cache?.mode === 'bypass') {
|
|
413
|
+
if (context?.abortSignal || context?.cache === false || context?.cache?.mode === 'bypass') {
|
|
408
414
|
return false;
|
|
409
415
|
}
|
|
410
416
|
const builderOverride = context?.runtime?.builderFactory;
|
|
@@ -470,53 +476,79 @@ export class DatasetClientImpl extends MetricQueryEngine {
|
|
|
470
476
|
return super.validate(target, query, context);
|
|
471
477
|
}
|
|
472
478
|
executeMetric(metric, query, context) {
|
|
479
|
+
const ds = getMetricRef(metric).dataset;
|
|
480
|
+
// Same ceiling and same cache policy as a dataset query: a metric is a
|
|
481
|
+
// named query over the dataset, not a way around what it declared.
|
|
482
|
+
const resultLimit = resolveResultLimit(query.limit, ds.limits);
|
|
483
|
+
const boundedQuery = resultLimit.limit === query.limit ? query : { ...query, limit: resultLimit.limit };
|
|
484
|
+
const cacheRuntime = this.datasetCacheContext(ds, context);
|
|
473
485
|
const run = () => {
|
|
474
486
|
if (this.backend) {
|
|
475
|
-
const validation = validateQuery(metric,
|
|
487
|
+
const validation = validateQuery(metric, boundedQuery, context);
|
|
476
488
|
if (!validation.valid) {
|
|
477
489
|
throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
|
|
478
490
|
}
|
|
479
|
-
return this.backend.execute(this.planMetric(metric,
|
|
491
|
+
return this.backend.execute(this.planMetric(metric, boundedQuery, context), { abortSignal: context?.abortSignal }).then((result) => ({
|
|
480
492
|
...result,
|
|
481
493
|
data: serializeSemanticMeasureValues(result.data, [getMetricRef(metric).name]),
|
|
482
494
|
}));
|
|
483
495
|
}
|
|
484
|
-
return this.run(metric,
|
|
496
|
+
return this.run(metric, boundedQuery, context);
|
|
485
497
|
};
|
|
486
|
-
if (!this.isCacheable(
|
|
487
|
-
return run();
|
|
498
|
+
if (!this.isCacheable(cacheRuntime)) {
|
|
499
|
+
return withResultLimit(run(), resultLimit.meta);
|
|
488
500
|
}
|
|
489
501
|
// Validate semantic rules before cache lookup so invalid queries and
|
|
490
502
|
// missing tenant runtime cannot be served from cache. Avoid this.validate()
|
|
491
503
|
// here because it dry-builds SQL, which is unnecessary on cache hits and
|
|
492
504
|
// invalid for backend-only clients.
|
|
493
|
-
const validation = validateQuery(metric,
|
|
505
|
+
const validation = validateQuery(metric, boundedQuery, context);
|
|
494
506
|
if (!validation.valid) {
|
|
495
507
|
throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
|
|
496
508
|
}
|
|
497
|
-
return this.queryCache.through(buildMetricQuerySignature(metric,
|
|
509
|
+
return withResultLimit(this.queryCache.through(buildMetricQuerySignature(metric, boundedQuery, this.signatureContext(cacheRuntime)), run, cacheRuntime?.cache), resultLimit.meta);
|
|
498
510
|
}
|
|
499
511
|
executeDataset(ds, query, context) {
|
|
500
512
|
const validation = this.validate(ds, query, context);
|
|
501
513
|
if (!validation.valid) {
|
|
502
514
|
throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
|
|
503
515
|
}
|
|
516
|
+
// Bound before the signature is built, so an unbounded call and an explicit
|
|
517
|
+
// call at the ceiling produce the same rows and share one cache entry.
|
|
518
|
+
const resultLimit = resolveResultLimit(query.limit, ds.limits);
|
|
519
|
+
const boundedQuery = resultLimit.limit === query.limit ? query : { ...query, limit: resultLimit.limit };
|
|
520
|
+
const cacheRuntime = this.datasetCacheContext(ds, context);
|
|
504
521
|
const run = () => {
|
|
505
522
|
if (this.backend) {
|
|
506
|
-
return this.backend.execute(this.planDataset(ds,
|
|
523
|
+
return this.backend.execute(this.planDataset(ds, boundedQuery, context), { abortSignal: context?.abortSignal }).then((result) => ({
|
|
507
524
|
...result,
|
|
508
|
-
data: serializeSemanticMeasureValues(result.data,
|
|
525
|
+
data: serializeSemanticMeasureValues(result.data,
|
|
526
|
+
// Same measures either way; boundedQuery differs only in `limit`.
|
|
527
|
+
boundedQuery.measures ?? Object.keys(ds.measures)),
|
|
509
528
|
}));
|
|
510
529
|
}
|
|
511
|
-
return runDatasetQuery(ds,
|
|
530
|
+
return runDatasetQuery(ds, boundedQuery, {
|
|
512
531
|
builderFactory: resolveBuilderFactory(context, this.getBuilderFactory()),
|
|
513
532
|
context,
|
|
514
533
|
});
|
|
515
534
|
};
|
|
516
|
-
if (!this.isCacheable(
|
|
517
|
-
return run();
|
|
535
|
+
if (!this.isCacheable(cacheRuntime)) {
|
|
536
|
+
return withResultLimit(run(), resultLimit.meta);
|
|
537
|
+
}
|
|
538
|
+
// Annotated outside the cache: the ceiling is derived from the query, not
|
|
539
|
+
// from the rows, so it must not be stored in or read back from an entry.
|
|
540
|
+
return withResultLimit(this.queryCache.through(buildDatasetQuerySignature(ds, boundedQuery, this.signatureContext(cacheRuntime)), run, cacheRuntime?.cache), resultLimit.meta);
|
|
541
|
+
}
|
|
542
|
+
/**
|
|
543
|
+
* Folds the dataset's declared cache policy into the call's context, so both
|
|
544
|
+
* the cacheability decision and the lookup see the same resolved TTL.
|
|
545
|
+
*/
|
|
546
|
+
datasetCacheContext(ds, context) {
|
|
547
|
+
const cache = resolveDatasetCacheRuntime(ds.cache, context?.cache, this.cacheDefaults);
|
|
548
|
+
if (cache === context?.cache) {
|
|
549
|
+
return context;
|
|
518
550
|
}
|
|
519
|
-
return
|
|
551
|
+
return { ...context, cache };
|
|
520
552
|
}
|
|
521
553
|
toDatasetSQL(ds, query, context) {
|
|
522
554
|
const builder = buildDatasetQueryBuilder(ds, query, {
|
package/dist/field.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAC;AAoBnF,eAAO,MAAM,SAAS;sBAhBZ,QAAQ,SAAS,gBAAgB,GAAG,SAAS;sBAA7C,QAAQ,SAAS,gBAAgB,GAAG,SAAS;uBAA7C,QAAQ,SAAS,gBAAgB,GAAG,SAAS;yBAA7C,QAAQ,SAAS,gBAAgB,GAAG,SAAS;CAqB7C,CAAC"}
|
package/dist/field.js
CHANGED
|
@@ -15,12 +15,14 @@
|
|
|
15
15
|
* });
|
|
16
16
|
* ```
|
|
17
17
|
*/
|
|
18
|
+
import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
|
|
18
19
|
function createFieldHelper(fieldType) {
|
|
19
20
|
return (opts) => ({
|
|
20
21
|
__type: 'field_definition',
|
|
21
22
|
fieldType,
|
|
22
23
|
label: opts?.label,
|
|
23
24
|
description: opts?.description,
|
|
25
|
+
...snapshotSemanticMetadata(opts ?? {}),
|
|
24
26
|
column: opts?.column,
|
|
25
27
|
sql: opts?.sql,
|
|
26
28
|
dependencies: opts?.dependencies,
|
package/dist/index.d.ts
CHANGED
|
@@ -6,16 +6,25 @@ export { sum, count, countDistinct, avg, min, max, percentile, median, argMax, a
|
|
|
6
6
|
export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, } from './formulas.js';
|
|
7
7
|
export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
|
|
8
8
|
export { createDatasetRegistry } from './registry.js';
|
|
9
|
+
export { publishDatasets } from './publishing/publisher.js';
|
|
10
|
+
export type { DatasetPublisher } from './publishing/publisher.js';
|
|
11
|
+
export type { PublishableMetric, PublishedMetricHandle, PublishedMetricMap, PublishedMetrics, PublishedDataset, PublishedDatasetRegistry, PublishDatasetOptions, } from './publishing/types.js';
|
|
9
12
|
export { getDatasetCatalog, getDatasetCatalogs, getQueryableRelationshipFields } from './catalog.js';
|
|
10
13
|
export { listQueryableRelationshipFields } from './utils/relationship-fields.js';
|
|
11
14
|
export type { DatasetCatalog, DatasetCatalogMap, DatasetCatalogSource, DimensionCatalogEntry, MeasureCatalogEntry, MetricCatalogEntry, FilterCatalogEntry, RelationshipCatalogEntry, } from './catalog.js';
|
|
15
|
+
export { DEFAULT_AGENT_CATALOG_MAX_BYTES, assertAgentSafeCatalogBudget, projectAgentSafeCatalog, projectTrustedDebugCatalog, } from './agent-catalog.js';
|
|
16
|
+
export type { AgentCatalogDataset, AgentCatalogDatasetRegistry, AgentCatalogProjectionOptions, AgentCatalogDimension, AgentCatalogFilter, AgentCatalogMeasure, AgentCatalogMetric, AgentCatalogRelationship, AgentCatalogSource, AgentSafeCatalog, TrustedDebugCatalog, TrustedDebugCatalogAuthorization, } from './agent-catalog.js';
|
|
12
17
|
export { serializeSemanticContract, contractToStableJson, hashContract, SEMANTIC_CONTRACT_VERSION, } from './contract.js';
|
|
18
|
+
export { rehydrateProtocolDatasets, UnsupportedContractFeatureError, } from './protocol-rehydrate.js';
|
|
19
|
+
export type { RehydratedDataset, RehydrateProtocolDatasetsOptions, } from './protocol-rehydrate.js';
|
|
13
20
|
export { buildProtocolDatasetContract } from './protocol-adapter.js';
|
|
14
21
|
export type { BuildProtocolDatasetContractOptions } from './protocol-adapter.js';
|
|
15
22
|
export { compilePortableSqlExpression, DEFAULT_SQL_PORTABILITY_LIMITS, } from './sql-portability.js';
|
|
16
23
|
export type { SqlPortabilityIssue, SqlPortabilityIssueCode, SqlPortabilityLimits, SqlPortabilityOptions, SqlPortabilityResult, } from './sql-portability.js';
|
|
17
24
|
export type { SemanticContract, SerializeSemanticContractOptions, ContractDataset, ContractDimension, ContractMeasure, ContractMetric, ContractFilter, ContractRelationship, } from './contract.js';
|
|
18
25
|
export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
|
|
26
|
+
export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, } from './semantic-query-schema.js';
|
|
27
|
+
export type { CanonicalSemanticQuerySchemas, SemanticMetricQueryContract, SemanticQuerySchemaLimits, SemanticQuerySchemaOptions, SemanticQuerySchemaSource, } from './semantic-query-schema.js';
|
|
19
28
|
export type { AISDKToolDefinition, DatasetToolAnalytics, DatasetToolMode, GenerateDatasetToolsOptions, JsonSchema, McpToolDefinition, OpenAIToolDefinition, SemanticToolDefinition, } from './tools.js';
|
|
20
29
|
export { createDatasetClient } from './executor.js';
|
|
21
30
|
export type { DatasetClient, CreateDatasetClientOptions } from './executor.js';
|
|
@@ -31,5 +40,5 @@ export type { QueryBuilderLike, QueryBuilderFactoryLike, QueryBuilderFactoryComp
|
|
|
31
40
|
export { toQueryBuilderFactory } from './query-builder-protocol.js';
|
|
32
41
|
export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
|
|
33
42
|
export { GRAIN_FUNCTIONS, SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
|
|
34
|
-
export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetLimits, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetQueryableDimensions, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetRowFor, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricRowFor, MetricResultFor, KnownStringKeys, } from './types.js';
|
|
43
|
+
export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetDefaults, DatasetFreshness, DatasetLimits, DatasetCachePolicy, SemanticMetadata, SemanticSensitivity, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetQueryableDimensions, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetRowFor, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricRowFor, MetricResultFor, KnownStringKeys, } from './types.js';
|
|
35
44
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGnI,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAC/B,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,KAAK,EAAE,IAAI,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EACzB,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAChC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,KAAK,GACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,cAAc,CAAC;AACrG,OAAO,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACjF,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,mCAAmC,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,gCAAgC,EAChC,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGnI,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAC/B,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,KAAK,EAAE,IAAI,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EACzB,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAChC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,KAAK,GACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,cAAc,CAAC;AACrG,OAAO,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACjF,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,+BAA+B,EAC/B,4BAA4B,EAC5B,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,gCAAgC,GACjC,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,iBAAiB,EACjB,gCAAgC,GACjC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,mCAAmC,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,gCAAgC,EAChC,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,kCAAkC,EAClC,oBAAoB,EACpB,oCAAoC,GACrC,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,2BAA2B,EAC3B,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAG/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC5E,YAAY,EACV,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxE,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGhG,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAGnG,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,YAAY,EACZ,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -14,17 +14,24 @@ export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ce
|
|
|
14
14
|
export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
|
|
15
15
|
// Registry
|
|
16
16
|
export { createDatasetRegistry } from './registry.js';
|
|
17
|
+
// First-class publication builder for Serve, MCP, and agent consumers.
|
|
18
|
+
export { publishDatasets } from './publishing/publisher.js';
|
|
17
19
|
// Catalog
|
|
18
20
|
export { getDatasetCatalog, getDatasetCatalogs, getQueryableRelationshipFields } from './catalog.js';
|
|
19
21
|
export { listQueryableRelationshipFields } from './utils/relationship-fields.js';
|
|
22
|
+
// Agent-safe and separately authorized trusted-debug catalog projections.
|
|
23
|
+
export { DEFAULT_AGENT_CATALOG_MAX_BYTES, assertAgentSafeCatalogBudget, projectAgentSafeCatalog, projectTrustedDebugCatalog, } from './agent-catalog.js';
|
|
20
24
|
// Semantic contract (stable, hashable export for snapshots/diffs/validation)
|
|
21
25
|
export { serializeSemanticContract, contractToStableJson, hashContract, SEMANTIC_CONTRACT_VERSION, } from './contract.js';
|
|
22
26
|
// Portable deployment contract adapter
|
|
27
|
+
export { rehydrateProtocolDatasets, UnsupportedContractFeatureError, } from './protocol-rehydrate.js';
|
|
23
28
|
export { buildProtocolDatasetContract } from './protocol-adapter.js';
|
|
24
29
|
// SQL portability compiler (R1A-07)
|
|
25
30
|
export { compilePortableSqlExpression, DEFAULT_SQL_PORTABILITY_LIMITS, } from './sql-portability.js';
|
|
26
31
|
// Agent/tool metadata
|
|
27
32
|
export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
|
|
33
|
+
// Canonical semantic query schemas shared by Serve, MCP, and agent adapters.
|
|
34
|
+
export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, } from './semantic-query-schema.js';
|
|
28
35
|
// Dataset client
|
|
29
36
|
export { createDatasetClient } from './executor.js';
|
|
30
37
|
// Semantic query result cache
|
package/dist/measure.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../src/measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../src/measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;AAiBxF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI3D;AAqBD,iBAAS,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,iBAAiB,CAcvG;AAED,eAAO,MAAM,OAAO;0BAtDH,MAAM,SAAS,cAAc,KAAG,iBAAiB;4BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;oCAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;IA6DhE,gFAAgF;;IAEhF,mDAAmD;6BACnC,MAAM,SAAS,cAAc,KAAG,iBAAiB;IAEjE;;;;;OAKG;6BAnDY,MAAM,MAAM,MAAM,SAAS,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,KAAG,iBAAiB;IAqD7F,gFAAgF;6BArDjE,MAAM,MAAM,MAAM,SAAS,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,KAAG,iBAAiB;IAuD7F,2DAA2D;6BA3E5C,MAAM,SAAS,cAAc,KAAG,iBAAiB;IA6EhE,8CAA8C;+BA7E/B,MAAM,SAAS,cAAc,KAAG,iBAAiB;CA+ExD,CAAC"}
|
package/dist/measure.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
|
|
1
2
|
function createMeasureHelper(aggregation) {
|
|
2
3
|
return (field, opts) => ({
|
|
3
4
|
__type: 'measure_definition',
|
|
@@ -7,6 +8,7 @@ function createMeasureHelper(aggregation) {
|
|
|
7
8
|
dependencies: opts?.dependencies,
|
|
8
9
|
label: opts?.label,
|
|
9
10
|
description: opts?.description,
|
|
11
|
+
...snapshotSemanticMetadata(opts ?? {}),
|
|
10
12
|
filters: opts?.filters,
|
|
11
13
|
});
|
|
12
14
|
}
|
|
@@ -29,6 +31,7 @@ function createArgMeasureHelper(aggregation) {
|
|
|
29
31
|
dependencies: opts?.dependencies,
|
|
30
32
|
label: opts?.label,
|
|
31
33
|
description: opts?.description,
|
|
34
|
+
...snapshotSemanticMetadata(opts ?? {}),
|
|
32
35
|
};
|
|
33
36
|
};
|
|
34
37
|
}
|
|
@@ -43,6 +46,7 @@ function createPercentileMeasure(field, level, opts) {
|
|
|
43
46
|
dependencies: opts?.dependencies,
|
|
44
47
|
label: opts?.label,
|
|
45
48
|
description: opts?.description,
|
|
49
|
+
...snapshotSemanticMetadata(opts ?? {}),
|
|
46
50
|
filters: opts?.filters,
|
|
47
51
|
};
|
|
48
52
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAI5B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,kBAAkB,EAIlB,YAAY,EAEb,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAI5B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,kBAAkB,EAIlB,YAAY,EAEb,MAAM,YAAY,CAAC;AAUpB,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAC7E;AAyLD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,mCAAwC,GAChD,uBAAuB,CAiHzB"}
|
package/dist/protocol-adapter.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateCanonicalValue, validateProtocolDatasetContract, } from '@hypequery/protocol';
|
|
2
2
|
import { SEMANTIC_FILTER_OPERATORS } from './constants.js';
|
|
3
|
+
import { toProtocolSemanticMetadata } from './utils/protocol-semantic-metadata.js';
|
|
3
4
|
function byName(left, right) {
|
|
4
5
|
return left.name.localeCompare(right.name);
|
|
5
6
|
}
|
|
@@ -134,6 +135,7 @@ function metricContract(exposedName, metric, endpoint) {
|
|
|
134
135
|
...(grain !== undefined ? { grain } : {}),
|
|
135
136
|
...(ref.label !== undefined ? { label: ref.label } : {}),
|
|
136
137
|
...(ref.description !== undefined ? { description: ref.description } : {}),
|
|
138
|
+
...toProtocolSemanticMetadata(ref),
|
|
137
139
|
endpoint,
|
|
138
140
|
};
|
|
139
141
|
return result;
|
|
@@ -170,7 +172,23 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
|
|
|
170
172
|
.sort(byName);
|
|
171
173
|
const contract = {
|
|
172
174
|
name: dataset.name,
|
|
175
|
+
...(dataset.description !== undefined ? { description: dataset.description } : {}),
|
|
176
|
+
...toProtocolSemanticMetadata(dataset),
|
|
173
177
|
source: dataset.source,
|
|
178
|
+
...(dataset.freshness !== undefined ? { freshness: { ...dataset.freshness } } : {}),
|
|
179
|
+
...(dataset.owner !== undefined ? { owner: dataset.owner } : {}),
|
|
180
|
+
...(dataset.defaults !== undefined
|
|
181
|
+
? {
|
|
182
|
+
defaults: {
|
|
183
|
+
...(dataset.defaults.dimensions !== undefined
|
|
184
|
+
? { dimensions: [...dataset.defaults.dimensions].map(parseProtocolIdentifier) }
|
|
185
|
+
: {}),
|
|
186
|
+
...(dataset.defaults.timeGrain !== undefined
|
|
187
|
+
? { timeGrain: dataset.defaults.timeGrain }
|
|
188
|
+
: {}),
|
|
189
|
+
},
|
|
190
|
+
}
|
|
191
|
+
: {}),
|
|
174
192
|
tenant: dataset.tenantKey
|
|
175
193
|
? { kind: 'required', field: dataset.tenantKey }
|
|
176
194
|
: { kind: 'not-required' },
|
|
@@ -185,6 +203,7 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
|
|
|
185
203
|
groupable: dimension.groupable !== false,
|
|
186
204
|
...(dimension.label !== undefined ? { label: dimension.label } : {}),
|
|
187
205
|
...(dimension.description !== undefined ? { description: dimension.description } : {}),
|
|
206
|
+
...toProtocolSemanticMetadata(dimension),
|
|
188
207
|
})).sort(byName),
|
|
189
208
|
measures: Object.entries(dataset.measures).map(([name, measure]) => ({
|
|
190
209
|
name,
|
|
@@ -200,6 +219,7 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
|
|
|
200
219
|
filters: (measure.filters ?? []).map(filterExpression),
|
|
201
220
|
...(measure.label !== undefined ? { label: measure.label } : {}),
|
|
202
221
|
...(measure.description !== undefined ? { description: measure.description } : {}),
|
|
222
|
+
...toProtocolSemanticMetadata(measure),
|
|
203
223
|
})).sort(byName),
|
|
204
224
|
filters: Object.entries(dataset.filters).map(([name, filter]) => ({
|
|
205
225
|
name,
|
|
@@ -207,6 +227,7 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
|
|
|
207
227
|
operators: [...(filter.operators ?? SEMANTIC_FILTER_OPERATORS)],
|
|
208
228
|
...(filter.label !== undefined ? { label: filter.label } : {}),
|
|
209
229
|
...(filter.description !== undefined ? { description: filter.description } : {}),
|
|
230
|
+
...toProtocolSemanticMetadata(filter),
|
|
210
231
|
})).sort(byName),
|
|
211
232
|
metrics,
|
|
212
233
|
relationships: Object.entries(dataset.relationships).map(([name, relationship]) => ({
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Rebuilds executable datasets from a portable deployment contract.
|
|
3
|
+
*
|
|
4
|
+
* The inverse of `protocol-adapter.ts`. Decision 0005 chose portable native
|
|
5
|
+
* execution, which means a runtime resolves a dataset from the validated active
|
|
6
|
+
* contract and plans the query with the existing semantic planner — no customer
|
|
7
|
+
* module is loaded. This is the function that makes the contract executable.
|
|
8
|
+
*
|
|
9
|
+
* Rehydration deliberately routes through the public `dataset()` factory rather
|
|
10
|
+
* than assembling an instance by hand, so a rebuilt dataset is constructed by
|
|
11
|
+
* exactly the same code path as an authored one. That is what makes the
|
|
12
|
+
* byte-identical SQL claim mitigated by construction rather than by review.
|
|
13
|
+
*/
|
|
14
|
+
import type { ProtocolDatasetContract } from '@hypequery/protocol';
|
|
15
|
+
import type { AnyDatasetInstance, DatasetCachePolicy, MetricHandle } from './types.js';
|
|
16
|
+
/** A rebuilt dataset in the registry shape Serve, MCP, and the planner accept. */
|
|
17
|
+
export type RehydratedDataset = AnyDatasetInstance & {
|
|
18
|
+
readonly metrics: Readonly<Record<string, MetricHandle>>;
|
|
19
|
+
};
|
|
20
|
+
export interface RehydrateProtocolDatasetsOptions {
|
|
21
|
+
/**
|
|
22
|
+
* Cache policy for the rebuilt datasets. Not carried by the contract — it is
|
|
23
|
+
* an operational concern of whoever runs the query, not of the deployment.
|
|
24
|
+
*/
|
|
25
|
+
readonly cache?: DatasetCachePolicy;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Thrown when a contract describes something portable execution cannot rebuild.
|
|
29
|
+
*
|
|
30
|
+
* Callers map this onto the `unsupported-capability` invocation failure rather
|
|
31
|
+
* than executing an approximation, as decision 0005 requires.
|
|
32
|
+
*/
|
|
33
|
+
export declare class UnsupportedContractFeatureError extends Error {
|
|
34
|
+
readonly dataset: string;
|
|
35
|
+
readonly feature: string;
|
|
36
|
+
constructor(datasetName: string, feature: string, detail: string);
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Rebuild every dataset in a validated deployment contract.
|
|
40
|
+
*
|
|
41
|
+
* Datasets are returned keyed by contract name with their named metrics
|
|
42
|
+
* attached, which is the registry shape `getDatasetCatalog`,
|
|
43
|
+
* `projectAgentSafeCatalog`, and `DatasetClient` already accept.
|
|
44
|
+
*/
|
|
45
|
+
export declare function rehydrateProtocolDatasets(contracts: readonly ProtocolDatasetContract[], options?: RehydrateProtocolDatasetsOptions): Readonly<Record<string, RehydratedDataset>>;
|
|
46
|
+
//# sourceMappingURL=protocol-rehydrate.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAGxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAIlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAKpB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMjE;AAmLD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,uBAAuB,EAAE,EAC7C,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CA8D7C"}
|