mammoth-cli 2.2.72__tar.gz → 2.2.73__tar.gz

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.72
+Version: 2.2.73
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.2.72"
+__version__ = "2.2.73"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -123,6 +123,15 @@ mammoth dashboard descriptor-data DASHBOARD_ID --input '{"body": {"params": {
 A card that reads the same with and without the filter, or a distinct count
 that equals a row count, is a wrong binding, not a data fact.
 
+## Limits
+
+- `v3 generate` takes one `dataview_id`; `chat edit` cannot add a tile from
+  another view. Join the data into one view first.
+- The smallest date grain is day (day/week/month/quarter/year): hourly data
+  shows as daily points.
+- Currently a view with no numeric column gets no table or bar chart. Add a
+  numeric column such as a count, or build from a view that has a measure.
+
 ## Canvas, widget data and PDF
 
 `dashboard canvas get DASHBOARD_ID` reads the canvas (`data.canvas` incl.

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/index.md

@@ -14,6 +14,7 @@ hashes; stop on ambiguous schemas, authorization errors, or unknown effects.
 - [files, datasets, views and settings](resources.md)
 - [import a table from a database (SQL Server, MySQL, Postgres)](database-import.md)
 - [import a file from an SFTP server](file-import.md)
+- [pull data from a REST API or Elasticsearch on a schedule](rest-api-import.md)
 - [datasets in `need_action` or `needs_view` after upload](need-action.md)
 - [typed transformations and drafts](transforms.md)
 - [typed ETL discovery](typed-etl-discovery.md)

mammoth_cli-2.2.73/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/rest-api-import.md

@@ -0,0 +1,91 @@
+# Pull data from a REST API (or Elasticsearch) on a schedule
+
+REST connection -> dataset -> scheduled refresh. Every connector command runs
+in a project (`--project PROJECT_ID`). The connector key is `generic_rest_api`.
+Creates and refreshes are writes: get the user's confirmation first.
+
+```bash
+mammoth connector get generic_rest_api         # spec.connection_config (has base_url) + spec.connection_input_note; spec.data_source_config = JSON schema of the query keys below, plus selected_columns, max_flatten_depth, join_tables, loop_over
+mammoth connector connection list generic_rest_api   # reuse a connection if one fits
+```
+
+## 1. Connection
+
+The body goes under `config`, with **flat** auth fields: `auth_type` (`none`,
+`api_key`, `bearer`, `basic`), then `username` +
+`password`, or `token`, or `key_name` + `key_value` + `inject_into`
+(`header|query_param`). Do not send a nested `auth` object: an older backend
+drops it and saves the connection as `auth_type: none` (the target API then
+answers 401 at sample time); a backend with the fix rejects it with 4CONN003 ("Create a connection with auth as flat fields ... not a nested 'auth' object"). The base URL must be
+a public host; localhost and private addresses are refused (SSRF guard).
+
+```bash
+# request.json (mode 0600): {"config": {"name": "My API", "base_url": "https://api.example.com/v1", "auth_type": "basic", "username": "u", "password": "p"}}
+mammoth connector connection create generic_rest_api --input request.json --yes
+```
+
+The reply holds `identity_key`: that is CONNECTION_KEY below. To change
+credentials later use `connector connection update ... --input` with
+`{"credentials": {...}}`, not `config`. Error 4SUBS007 means the workspace plan
+does not include this connector (or its paid addon is not active).
+
+## 2. Try the data-source config (creates no dataset)
+
+`query` is a **JSON string** (not an object) of the data-source config:
+`endpoint_path`, `http_method` (`GET|POST`), `request_body`, `query_params`,
+`data_root_path` (JSONPath to the records; `[*]` is supported), `pagination`,
+`flatten_nested_json`, `max_pages`.
+
+```bash
+# sample.json: {"query": "{\"endpoint_path\": \"/posts\", \"data_root_path\": \"$\", \"max_pages\": 1}", "validate": false, "data_sample": true}
+mammoth connector ds-config create generic_rest_api CONNECTION_KEY --input sample.json --yes
+```
+
+Needs `--yes`; returns real sample rows (50 for a composite-agg
+`data_root_path`). Read the column names from `data.data_sample.dataschema`.
+`ds-config list generic_rest_api CONNECTION_KEY` shows the connection's configs
+(`config_key`, `ds_name`, `on_refresh_action`, `query`, `table`, `profile`);
+`ds-config get generic_rest_api CONNECTION_KEY CONFIG_KEY` returns one under
+`ds_config`. A REST config has `data_start_date: null`. A dataset's config key
+is `dataset get` -> `sources[0].details.id`.
+
+## 3. Dataset with a refresh schedule
+
+`schedule_properties` and `recurrence_info` are required; without them the job
+fails with "Invalid parameters". `on_refresh_action` is `replace` (swap the
+rows each refresh) or `combine` (append: every refresh re-adds every row the
+API returns, so rows duplicate).
+
+```bash
+# dataset.json
+# {"ds_creation_type": "cloud", "dataset_spec": {"connector_key": "generic_rest_api",
+#   "connection_key": "CONNECTION_KEY",
+#   "query_properties": {"ds_name": "My data", "table_name": "posts", "query": "<same JSON string as step 2>"},
+#   "schedule_properties": {"schedule_type": "moment", "first_pull_at": "now", "on_refresh_action": "replace"},
+#   "recurrence_info": {"interval": 1, "start_at": "2027-01-01T02:00:00"}}}
+mammoth dataset create --input dataset.json
+```
+
+## 4. Refresh automatically
+
+```bash
+# auto.json: {"description": "Refresh My data", "tasks": [{"task_type": "run_data_retrieval", "details": {"ds_details": [{"ds_id": DATASET_ID}]}}],
+#   "conditions": [{"condition_type": "at_specific_time", "details": {"frequency": "daily", "interval": 1, "start_at": "2027-01-01T02:00:00Z"}}]}
+mammoth automation create 'Refresh My data' --input auto.json --yes   # name required; ds_details must be a list
+mammoth automation update AUTOMATION_ID --yes --input '{"patch": [{"op": "command", "path": "run", "value": {}}]}'   # run now
+```
+
+A `start_at` under 2 minutes ahead is rejected ("too soon"); a past one starts now.
+More on automations: [recurring work](scheduling.md).
+
+## Elasticsearch
+
+Use the connection above with `base_url` of the cluster and `POST` on
+`/INDEX/_search`. Name the fields you need in `_source`: a field such as
+`asctime` ("2026-10-09 15:52:46,290", comma before the millis) breaks the load.
+
+- Documents: `"request_body": {"size": 500, "_source": ["@timestamp", "task"]}`,
+  `"data_root_path": "$.hits.hits[*]._source"`.
+- Counts per bucket: `"request_body": {"size": 0, "aggs": {"c": {"composite": {"size": 10000, "sources": [...]}}}}`,
+  `"data_root_path": "$.aggregations.c.buckets[*]"` gives columns `doc_count`,
+  `key.<source>`.

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/scheduling.md

@@ -120,7 +120,8 @@ If one exists, change it with `automation update AUTOMATION_ID` (see below)
 instead of creating another. Before a schedule that emails a client, send the
 same email to the user first (or `--dry-run` the create and show the
 recipients, subject and attached views) and get a yes. Give `start_at` a time
-in the future; a past `start_at` may fire straight away or never.
+in the future: under 2 minutes ahead is rejected ("too soon"), a later one is
+stored as sent, a past one starts now.
 
 ## Read it back
 

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/mammoth_cli/commands/connector.py

@@ -360,7 +360,7 @@ def connector_connection_update(invocation: Invocation) -> HandlerResult:
 
 
 def connector_ds_config_create(invocation: Invocation) -> HandlerResult:
-    """Create a data source configuration. ``--yes`` is always required."""
+    """Sample a data source config; REST ``query`` is a JSON string. ``--yes`` always needed."""
     project_id = require_project(invocation)
     connector_key = _require_string_positional_at(invocation, 0, "connector key")
     connection_key = _require_string_positional_at(invocation, 1, "connection key")

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/mammoth_cli/commands/help_summaries.json

@@ -138,7 +138,7 @@
   "connector.connection.get": "Get one connection's details. Connector and connection keys are positional.",
   "connector.connection.list": "List connections for a connector type; find its key with `mammoth connector active`.",
   "connector.connection.update": "Update a connection's credentials. '--yes' is always required.",
-  "connector.ds-config.create": "Create a data source configuration. '--yes' is always required.",
+  "connector.ds-config.create": "Sample a data source config; REST 'query' is a JSON string. '--yes' always needed.",
   "connector.ds-config.delete": "Delete a data source configuration. Prompt or '--yes' required.",
   "connector.ds-config.delete-all": "Bulk-delete data source configurations for a connection. Prompt or '--yes' required.",
   "connector.ds-config.get": "Get one data source configuration by key.",

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/mammoth_cli/commands/schema.py

@@ -405,7 +405,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
     ),
     "connector.get": (
         "connector database SQL Server MSSQL MySQL Postgres SFTP file server connection fields "
-        "host port username password required to connect import table file dataset"
+        "host port username password required to connect import table file dataset "
+        "REST API Elasticsearch generic_rest_api config schema"
     ),
     "connector.connection.list": (
         "which outside external sources connected connections list database SQL Server "
@@ -419,11 +420,12 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "connector.connection.create": (
         "connect a database such as SQL Server MSSQL MySQL Postgres Oracle or an SFTP file "
         "server host port username password new connection connector to import a table or "
-        "file into a dataset"
+        "file into a dataset, or a REST API or Elasticsearch generic_rest_api base_url"
     ),
     "connector.ds-config.create": (
         "import pull load read retrieve a table or SQL query from a connected database such "
-        "as SQL Server MSSQL MySQL Postgres connector connection as a new dataset rows data"
+        "as SQL Server MSSQL MySQL Postgres connector connection as a new dataset rows data "
+        "REST API Elasticsearch sample validate"
     ),
     "connector.ds-config.list": (
         "datasets imported from a connected database SQL Server MSSQL MySQL Postgres "
@@ -548,7 +550,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
     # it just had no discovery-purpose text at all.
     "dataset.create": (
         "url web link fetch retrieve pull import public website endpoint api json data weburl "
-        "file csv from an SFTP server folder cloud storage connection connector as a new dataset"
+        "file csv from an SFTP server folder cloud storage connection connector as a new dataset "
+        "REST API Elasticsearch generic_rest_api on a schedule refresh recurring"
     ),
     "dashboard.v3.generate": (
         "create build make new generate dashboard board report from a view description "

{mammoth_cli-2.2.72 → mammoth_cli-2.2.73}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.72"
+version = "2.2.73"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"