@lightdash/common 1.257.1 → 1.258.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.
Files changed (37) hide show
  1. package/dist/cjs/.tsbuildinfo +1 -1
  2. package/dist/cjs/ee/AiAgent/schemas/tools/toolDefinitions.d.ts +2 -2
  3. package/dist/cjs/ee/AiAgent/schemas/tools/toolDefinitions.d.ts.map +1 -1
  4. package/dist/cjs/ee/AiAgent/schemas/tools/toolDefinitions.js +4 -2
  5. package/dist/cjs/ee/AiAgent/schemas/tools/toolDefinitions.js.map +1 -1
  6. package/dist/cjs/ee/AiAgent/schemas/tools/toolRunQueryArgs.d.ts +3608 -1357
  7. package/dist/cjs/ee/AiAgent/schemas/tools/toolRunQueryArgs.d.ts.map +1 -1
  8. package/dist/cjs/ee/AiAgent/schemas/tools/toolRunQueryArgs.js +17 -6
  9. package/dist/cjs/ee/AiAgent/schemas/tools/toolRunQueryArgs.js.map +1 -1
  10. package/dist/cjs/ee/AiAgent/schemas/tools/toolRunQueryArgs.test.js +33 -0
  11. package/dist/cjs/ee/AiAgent/schemas/tools/toolRunQueryArgs.test.js.map +1 -1
  12. package/dist/cjs/schemas/json/mcp-tools-1.0.json +36 -400
  13. package/dist/esm/.tsbuildinfo +1 -1
  14. package/dist/esm/ee/AiAgent/schemas/tools/toolDefinitions.d.ts +2 -2
  15. package/dist/esm/ee/AiAgent/schemas/tools/toolDefinitions.d.ts.map +1 -1
  16. package/dist/esm/ee/AiAgent/schemas/tools/toolDefinitions.js +4 -2
  17. package/dist/esm/ee/AiAgent/schemas/tools/toolDefinitions.js.map +1 -1
  18. package/dist/esm/ee/AiAgent/schemas/tools/toolRunQueryArgs.d.ts +3608 -1357
  19. package/dist/esm/ee/AiAgent/schemas/tools/toolRunQueryArgs.d.ts.map +1 -1
  20. package/dist/esm/ee/AiAgent/schemas/tools/toolRunQueryArgs.js +16 -5
  21. package/dist/esm/ee/AiAgent/schemas/tools/toolRunQueryArgs.js.map +1 -1
  22. package/dist/esm/ee/AiAgent/schemas/tools/toolRunQueryArgs.test.js +34 -1
  23. package/dist/esm/ee/AiAgent/schemas/tools/toolRunQueryArgs.test.js.map +1 -1
  24. package/dist/esm/schemas/json/mcp-tools-1.0.json +36 -400
  25. package/dist/types/.tsbuildinfo +1 -1
  26. package/dist/types/ee/AiAgent/schemas/tools/toolDefinitions.d.ts +2 -2
  27. package/dist/types/ee/AiAgent/schemas/tools/toolDefinitions.d.ts.map +1 -1
  28. package/dist/types/ee/AiAgent/schemas/tools/toolDefinitions.js +4 -2
  29. package/dist/types/ee/AiAgent/schemas/tools/toolDefinitions.js.map +1 -1
  30. package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.d.ts +3608 -1357
  31. package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.d.ts.map +1 -1
  32. package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.js +16 -5
  33. package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.js.map +1 -1
  34. package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.test.js +34 -1
  35. package/dist/types/ee/AiAgent/schemas/tools/toolRunQueryArgs.test.js.map +1 -1
  36. package/dist/types/schemas/json/mcp-tools-1.0.json +36 -400
  37. package/package.json +1 -1
@@ -5496,414 +5496,50 @@
5496
5496
  "type": "array"
5497
5497
  },
5498
5498
  "tableCalculations": {
5499
- "description": "\nTable calculations perform row-by-row calculations on query results without collapsing rows. Similar to SQL window functions.\n\n**Prefer type \"formula\"** — it expresses arithmetic across fields, ratios, comparisons, conditionals, and partitioned window calculations. The other types are legacy single-field templates kept for backwards compatibility.\n\n**Technical Requirements:**\n- Appear as additional columns in query results\n- Can be used in sorts and filters alongside dimensions/metrics\n- Multiple calculations can be combined in a single query\n- All fields referenced must exist in the query (dimensions, metrics, or other table calculations)\n, ",
5499
+ "description": "\nTable calculations perform row-by-row calculations on query results without collapsing rows, using spreadsheet-like formulas.\n\nUse them whenever the question needs math the metric query alone can't express: arithmetic across metrics (`metric_a + metric_b`), ratios, percent of total, period-over-period change, running totals, moving averages, ranking, row-level comparisons, or aggregating already-aggregated metrics.\n\n**Technical Requirements:**\n- Appear as additional columns in query results\n- Can be used in sorts and filters alongside dimensions/metrics\n- Multiple calculations can be combined in a single query; a formula can reference another table calculation by name\n- All fields referenced must be selected in the query (dimensions, metrics, custom metrics, or other table calculations)\n, ",
5500
5500
  "items": {
5501
- "anyOf": [
5502
- {
5503
- "additionalProperties": false,
5504
- "properties": {
5505
- "displayName": {
5506
- "description": "Display name for the table calculation, e.g. \"MoM revenue change\"",
5507
- "type": "string"
5508
- },
5509
- "format": {
5510
- "description": "Display format. Use \"percent\" for ratios/shares/percent changes (value 0.12 renders as 12%). null defaults to \"number\"., ",
5511
- "enum": [
5512
- "number",
5513
- "percent"
5514
- ],
5515
- "type": "string"
5516
- },
5517
- "formula": {
5518
- "description": "Spreadsheet-like formula evaluated row-by-row over the query results (after aggregation).\nReference fields by their field id directly, e.g. `orders_total_revenue / orders_order_count`. No prefix, no braces, no leading `=`.\nAny selected dimension, metric, custom metric (`<table>_<name>`), or another table calculation name can be referenced.\nOperators: + - * / % ^, comparisons = < > <= >= <>, boolean AND/OR/NOT, string literals in double quotes, parentheses for grouping.\nFunctions include IF, COALESCE, ROUND, ABS, CONCAT, date functions (YEAR, DATE_TRUNC, DATE_DIFF, DATE_ADD), aggregates over the whole result (SUM, AVG, MIN, MAX, COUNT, SUMIF), and window functions (RUNNING_TOTAL, MOVING_SUM, MOVING_AVG, LAG, LEAD, RANK, DENSE_RANK, ROW_NUMBER, FIRST, LAST).\nWindow functions accept optional PARTITION BY / ORDER BY clauses as trailing arguments, e.g. `LAG(orders_total_revenue, PARTITION BY orders_status, ORDER BY orders_order_date)`.\nMOVING_SUM and MOVING_AVG take the count of preceding rows as second argument; the current row is always included, so a trailing 3-period average is `MOVING_AVG(orders_total_revenue, 2, ORDER BY orders_order_month)`.\nAll branches of an IF must return the same type.",
5519
- "type": "string"
5520
- },
5521
- "name": {
5522
- "description": "Unique name for the table calculation, e.g. \"percent_change_from_previous\"",
5523
- "type": "string"
5524
- },
5525
- "resultType": {
5526
- "description": "Data type the formula evaluates to. null defaults to \"number\"., ",
5527
- "enum": [
5528
- "number",
5529
- "string",
5530
- "date",
5531
- "timestamp",
5532
- "boolean"
5533
- ],
5534
- "type": "string"
5535
- },
5536
- "type": {
5537
- "const": "formula",
5538
- "type": "string"
5539
- }
5540
- },
5541
- "required": [
5542
- "name",
5543
- "displayName",
5544
- "type",
5545
- "formula"
5546
- ],
5547
- "type": "object"
5548
- },
5549
- {
5550
- "additionalProperties": false,
5551
- "properties": {
5552
- "displayName": {
5553
- "description": "Display name for the table calculation, e.g. \"MoM revenue change\"",
5554
- "type": "string"
5555
- },
5556
- "fieldId": {
5557
- "description": "Field whose values you want to compare \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5558
- "type": "string"
5559
- },
5560
- "name": {
5561
- "description": "Unique name for the table calculation, e.g. \"percent_change_from_previous\"",
5562
- "type": "string"
5563
- },
5564
- "orderBy": {
5565
- "description": "Specifies the order in which rows are processed by the table calculation.\nFor time-series: typically order by date/time ascending.\nFor rankings: order by the metric you want to rank, descending for highest-first.",
5566
- "items": {
5567
- "additionalProperties": false,
5568
- "properties": {
5569
- "fieldId": {
5570
- "description": "Field to order by \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5571
- "type": "string"
5572
- },
5573
- "order": {
5574
- "description": ", ",
5575
- "enum": [
5576
- "asc",
5577
- "desc"
5578
- ],
5579
- "type": "string"
5580
- }
5581
- },
5582
- "required": ["fieldId"],
5583
- "type": "object"
5584
- },
5585
- "minItems": 1,
5586
- "type": "array"
5587
- },
5588
- "partitionBy": {
5589
- "description": "Fields to PARTITION BY - divides result set into independent groups.\nEach partition calculates independently (rankings restart, percentages sum to 100% per partition).\nEmpty array or null: single partition (calculations across all rows)., ",
5590
- "items": {
5591
- "description": "\"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5592
- "type": "string"
5593
- },
5594
- "type": "array"
5595
- },
5596
- "type": {
5597
- "const": "percent_change_from_previous",
5598
- "type": "string"
5599
- }
5600
- },
5601
- "required": [
5602
- "name",
5603
- "displayName",
5604
- "type",
5605
- "fieldId",
5606
- "orderBy"
5607
- ],
5608
- "type": "object"
5501
+ "additionalProperties": false,
5502
+ "properties": {
5503
+ "displayName": {
5504
+ "description": "Display name for the table calculation, e.g. \"MoM revenue change\"",
5505
+ "type": "string"
5609
5506
  },
5610
- {
5611
- "additionalProperties": false,
5612
- "properties": {
5613
- "displayName": {
5614
- "description": "Display name for the table calculation, e.g. \"MoM revenue change\"",
5615
- "type": "string"
5616
- },
5617
- "fieldId": {
5618
- "description": "Field whose values you want to compare \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5619
- "type": "string"
5620
- },
5621
- "name": {
5622
- "description": "Unique name for the table calculation, e.g. \"percent_change_from_previous\"",
5623
- "type": "string"
5624
- },
5625
- "orderBy": {
5626
- "description": "Specifies the order in which rows are processed by the table calculation.\nFor time-series: typically order by date/time ascending.\nFor rankings: order by the metric you want to rank, descending for highest-first.",
5627
- "items": {
5628
- "additionalProperties": false,
5629
- "properties": {
5630
- "fieldId": {
5631
- "description": "Field to order by \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5632
- "type": "string"
5633
- },
5634
- "order": {
5635
- "description": ", ",
5636
- "enum": [
5637
- "asc",
5638
- "desc"
5639
- ],
5640
- "type": "string"
5641
- }
5642
- },
5643
- "required": ["fieldId"],
5644
- "type": "object"
5645
- },
5646
- "minItems": 1,
5647
- "type": "array"
5648
- },
5649
- "partitionBy": {
5650
- "description": "Fields to PARTITION BY - divides result set into independent groups.\nEach partition calculates independently (rankings restart, percentages sum to 100% per partition).\nEmpty array or null: single partition (calculations across all rows)., ",
5651
- "items": {
5652
- "description": "\"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5653
- "type": "string"
5654
- },
5655
- "type": "array"
5656
- },
5657
- "type": {
5658
- "const": "percent_of_previous_value",
5659
- "type": "string"
5660
- }
5661
- },
5662
- "required": [
5663
- "name",
5664
- "displayName",
5665
- "type",
5666
- "fieldId",
5667
- "orderBy"
5668
- ],
5669
- "type": "object"
5507
+ "format": {
5508
+ "description": "Display format. Use \"percent\" for ratios/shares/percent changes (value 0.12 renders as 12%). null defaults to \"number\"., ",
5509
+ "enum": ["number", "percent"],
5510
+ "type": "string"
5670
5511
  },
5671
- {
5672
- "additionalProperties": false,
5673
- "properties": {
5674
- "displayName": {
5675
- "description": "Display name for the table calculation, e.g. \"MoM revenue change\"",
5676
- "type": "string"
5677
- },
5678
- "fieldId": {
5679
- "description": "Field to calculate percentage of column total \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5680
- "type": "string"
5681
- },
5682
- "name": {
5683
- "description": "Unique name for the table calculation, e.g. \"percent_change_from_previous\"",
5684
- "type": "string"
5685
- },
5686
- "partitionBy": {
5687
- "description": "Fields to PARTITION BY - divides result set into independent groups.\nEach partition calculates independently (rankings restart, percentages sum to 100% per partition).\nEmpty array or null: single partition (calculations across all rows)., ",
5688
- "items": {
5689
- "description": "\"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5690
- "type": "string"
5691
- },
5692
- "type": "array"
5693
- },
5694
- "type": {
5695
- "const": "percent_of_column_total",
5696
- "type": "string"
5697
- }
5698
- },
5699
- "required": [
5700
- "name",
5701
- "displayName",
5702
- "type",
5703
- "fieldId"
5704
- ],
5705
- "type": "object"
5512
+ "formula": {
5513
+ "description": "Spreadsheet-like formula evaluated row-by-row over the query results (after aggregation).\nReference fields by their field id directly, e.g. `orders_total_revenue / orders_order_count`. No prefix, no braces, no leading `=`.\nAny selected dimension, metric, custom metric (`<table>_<name>`), or another table calculation name can be referenced.\nOperators: + - * / % ^, comparisons = < > <= >= <>, boolean AND/OR/NOT, string literals in double quotes, parentheses for grouping.\nFunctions include IF, COALESCE, ROUND, ABS, CONCAT, date functions (YEAR, DATE_TRUNC, DATE_DIFF, DATE_ADD), aggregates over the whole result (SUM, AVG, MIN, MAX, COUNT, SUMIF), and window functions (RUNNING_TOTAL, MOVING_SUM, MOVING_AVG, LAG, LEAD, RANK, DENSE_RANK, ROW_NUMBER, FIRST, LAST).\nWindow functions accept optional PARTITION BY / ORDER BY clauses as trailing arguments, e.g. `LAG(orders_total_revenue, PARTITION BY orders_status, ORDER BY orders_order_date)`.\nMOVING_SUM and MOVING_AVG take the count of preceding rows as second argument; the current row is always included, so a trailing 3-period average is `MOVING_AVG(orders_total_revenue, 2, ORDER BY orders_order_month)`.\nAll branches of an IF must return the same type.",
5514
+ "type": "string"
5706
5515
  },
5707
- {
5708
- "additionalProperties": false,
5709
- "properties": {
5710
- "displayName": {
5711
- "description": "Display name for the table calculation, e.g. \"MoM revenue change\"",
5712
- "type": "string"
5713
- },
5714
- "fieldId": {
5715
- "description": "Field to rank by \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5716
- "type": "string"
5717
- },
5718
- "name": {
5719
- "description": "Unique name for the table calculation, e.g. \"percent_change_from_previous\"",
5720
- "type": "string"
5721
- },
5722
- "type": {
5723
- "const": "rank_in_column",
5724
- "type": "string"
5725
- }
5726
- },
5727
- "required": [
5728
- "name",
5729
- "displayName",
5730
- "type",
5731
- "fieldId"
5732
- ],
5733
- "type": "object"
5516
+ "name": {
5517
+ "description": "Unique name for the table calculation, e.g. \"percent_change_from_previous\"",
5518
+ "type": "string"
5734
5519
  },
5735
- {
5736
- "additionalProperties": false,
5737
- "properties": {
5738
- "displayName": {
5739
- "description": "Display name for the table calculation, e.g. \"MoM revenue change\"",
5740
- "type": "string"
5741
- },
5742
- "fieldId": {
5743
- "description": "Field to calculate running total of \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5744
- "type": "string"
5745
- },
5746
- "name": {
5747
- "description": "Unique name for the table calculation, e.g. \"percent_change_from_previous\"",
5748
- "type": "string"
5749
- },
5750
- "type": {
5751
- "const": "running_total",
5752
- "type": "string"
5753
- }
5754
- },
5755
- "required": [
5756
- "name",
5757
- "displayName",
5758
- "type",
5759
- "fieldId"
5520
+ "resultType": {
5521
+ "description": "Data type the formula evaluates to. null defaults to \"number\"., ",
5522
+ "enum": [
5523
+ "number",
5524
+ "string",
5525
+ "date",
5526
+ "timestamp",
5527
+ "boolean"
5760
5528
  ],
5761
- "type": "object"
5529
+ "type": "string"
5762
5530
  },
5763
- {
5764
- "additionalProperties": false,
5765
- "properties": {
5766
- "displayName": {
5767
- "description": "Display name for the table calculation, e.g. \"MoM revenue change\"",
5768
- "type": "string"
5769
- },
5770
- "fieldId": {
5771
- "description": "Field to aggregate (required for sum/avg/count/min/max, not used for row_number/percent_rank/cume_dist/rank) \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error, Field to aggregate (required for sum/avg/count/min/max, not used for row_number/percent_rank/cume_dist/rank) \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5772
- "type": "string"
5773
- },
5774
- "frame": {
5775
- "additionalProperties": false,
5776
- "description": "Defines which rows to include in calculation. Null uses database defaults.\n\n**Common patterns:**\n- Moving average (N periods): {frameType: \"rows\", start: {type: \"preceding\", offset: N-1}, end: {type: \"current_row\"}}\n- Running total: {frameType: \"rows\", start: {type: \"unbounded_preceding\"}, end: {type: \"current_row\"}}\n- Centered window: {frameType: \"rows\", start: {type: \"preceding\", offset: 1}, end: {type: \"following\", offset: 1}}\n\n**Default when null:**\n- Aggregates WITH ORDER BY: RANGE UNBOUNDED PRECEDING AND CURRENT ROW (cumulative)\n- Aggregates WITHOUT ORDER BY: Entire partition (all rows)\n- Ranking functions: Always use entire partition (frame clause has no effect), ",
5777
- "properties": {
5778
- "end": {
5779
- "additionalProperties": false,
5780
- "description": "End boundary (required)",
5781
- "properties": {
5782
- "offset": {
5783
- "description": "Number of rows for PRECEDING/FOLLOWING, ",
5784
- "exclusiveMinimum": 0,
5785
- "type": "integer"
5786
- },
5787
- "type": {
5788
- "enum": [
5789
- "unbounded_preceding",
5790
- "preceding",
5791
- "current_row",
5792
- "following",
5793
- "unbounded_following"
5794
- ],
5795
- "type": "string"
5796
- }
5797
- },
5798
- "required": [
5799
- "type"
5800
- ],
5801
- "type": "object"
5802
- },
5803
- "frameType": {
5804
- "description": "Frame type:\n- rows: Physical row count\n- range: Logical value-based (includes peer rows with same ORDER BY value)",
5805
- "enum": [
5806
- "rows",
5807
- "range"
5808
- ],
5809
- "type": "string"
5810
- },
5811
- "start": {
5812
- "additionalProperties": false,
5813
- "description": "Start boundary. Null for single-boundary syntax., ",
5814
- "properties": {
5815
- "offset": {
5816
- "description": "Number of rows for PRECEDING/FOLLOWING (e.g., 6 for \"6 PRECEDING\"), ",
5817
- "exclusiveMinimum": 0,
5818
- "type": "integer"
5819
- },
5820
- "type": {
5821
- "enum": [
5822
- "unbounded_preceding",
5823
- "preceding",
5824
- "current_row",
5825
- "following",
5826
- "unbounded_following"
5827
- ],
5828
- "type": "string"
5829
- }
5830
- },
5831
- "required": [
5832
- "type"
5833
- ],
5834
- "type": "object"
5835
- }
5836
- },
5837
- "required": [
5838
- "frameType",
5839
- "end"
5840
- ],
5841
- "type": "object"
5842
- },
5843
- "name": {
5844
- "description": "Unique name for the table calculation, e.g. \"percent_change_from_previous\"",
5845
- "type": "string"
5846
- },
5847
- "orderBy": {
5848
- "description": "Specifies the order in which rows are processed by the table calculation.\nFor time-series: typically order by date/time ascending.\nFor rankings: order by the metric you want to rank, descending for highest-first., ",
5849
- "items": {
5850
- "additionalProperties": false,
5851
- "properties": {
5852
- "fieldId": {
5853
- "description": "Field to order by \"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5854
- "type": "string"
5855
- },
5856
- "order": {
5857
- "description": ", ",
5858
- "enum": [
5859
- "asc",
5860
- "desc"
5861
- ],
5862
- "type": "string"
5863
- }
5864
- },
5865
- "required": ["fieldId"],
5866
- "type": "object"
5867
- },
5868
- "type": "array"
5869
- },
5870
- "partitionBy": {
5871
- "description": "Fields to PARTITION BY - divides result set into independent groups.\nEach partition calculates independently (rankings restart, percentages sum to 100% per partition).\nEmpty array or null: single partition (calculations across all rows)., ",
5872
- "items": {
5873
- "description": "\"fieldId\" must come from the previously searched Fields; otherwise, it will throw an error",
5874
- "type": "string"
5875
- },
5876
- "type": "array"
5877
- },
5878
- "type": {
5879
- "const": "window_function",
5880
- "type": "string"
5881
- },
5882
- "windowFunction": {
5883
- "description": "Type of window function to apply.\n\n**Ranking functions** (fieldId optional, ignored if provided):\n- row_number: Sequential numbering (1, 2, 3...)\n- percent_rank: Relative rank as percentage (0.0-1.0)\n- cume_dist: Cumulative distribution as percentage (0.0-1.0)\n- rank: Positional rank (1, 2, 3...) with ties\n\n**Aggregate functions** (fieldId required):\n- sum: Sum values within frame\n- avg: Average values within frame\n- count: Count values within frame\n- min: Minimum value within frame\n- max: Maximum value within frame",
5884
- "enum": [
5885
- "row_number",
5886
- "percent_rank",
5887
- "cume_dist",
5888
- "rank",
5889
- "sum",
5890
- "avg",
5891
- "count",
5892
- "min",
5893
- "max"
5894
- ],
5895
- "type": "string"
5896
- }
5897
- },
5898
- "required": [
5899
- "name",
5900
- "displayName",
5901
- "type",
5902
- "windowFunction"
5903
- ],
5904
- "type": "object"
5531
+ "type": {
5532
+ "const": "formula",
5533
+ "type": "string"
5905
5534
  }
5906
- ]
5535
+ },
5536
+ "required": [
5537
+ "name",
5538
+ "displayName",
5539
+ "type",
5540
+ "formula"
5541
+ ],
5542
+ "type": "object"
5907
5543
  },
5908
5544
  "type": "array"
5909
5545
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lightdash/common",
3
- "version": "1.257.1",
3
+ "version": "1.258.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",