dataiku-sdk 3.2.0 → 3.4.0

package/dist/src/cli/commands/data-collection.js

@@ -0,0 +1,164 @@
+import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { planResult, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+const PLAN_FAILURE_CODES = { usage: 1, error: 2, transient: 3, };
+function collectionEndpoint(dataCollectionId, suffix = "") {
+    return `/public/api/data-collections/${encodeURIComponent(dataCollectionId)}${suffix}`;
+}
+export const dataCollectionCommands = {
+    list: {
+        handler: (c) => c.dataCollections.list(),
+        usage: "dss data-collection list",
+        description: "List data collections on which the API key has READ privilege.",
+        examples: ["dss data-collection list",],
+    },
+    get: {
+        handler: (c, a) => {
+            requireArgs(a, 1, "dss data-collection get <dataCollectionId>");
+            return c.dataCollections.get(a[0]);
+        },
+        usage: "dss data-collection get <dataCollectionId>",
+        description: "Get collection settings. Permissions are omitted for non-admins.",
+        examples: ["dss data-collection get OjVsTQ3O",],
+    },
+    create: {
+        handler: async (c, _a, f) => {
+            const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (collection definition).");
+            if (executionMode(f).dryRun) {
+                return planResult("data-collection", "create", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: "/public/api/data-collections/",
+                    payload: body,
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            return c.dataCollections.create(body);
+        },
+        usage: "dss data-collection create (--data JSON|--data-file PATH|--stdin) [--dry-run]",
+        description: "Create a collection (creator becomes admin; requires mayCreateDataCollections).",
+        examples: [
+            'dss data-collection create --data \'{"displayName":"My Collection"}\'',
+        ],
+    },
+    "settings-set": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss data-collection settings-set <dataCollectionId> (--data JSON|--data-file PATH|--stdin) [--dry-run]");
+            const settings = requiredJsonInput(f, "--data, --data-file, or --stdin is required (collection settings).");
+            if (executionMode(f).dryRun) {
+                return planResult("data-collection", "settings-set", {
+                    asyncKind: "none",
+                    method: "PUT",
+                    endpoint: collectionEndpoint(a[0]),
+                    identifiers: { dataCollectionId: a[0], },
+                    payload: settings,
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            const updated = await c.dataCollections.update(a[0], settings);
+            return { updated: a[0], resource: "data-collection", ...updated, };
+        },
+        usage: "dss data-collection settings-set <dataCollectionId> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
+        description: "Update collection settings; only send settings obtained through get. Admin required.",
+        examples: [
+            "dss data-collection settings-set OjVsTQ3O --data-file settings.json",
+        ],
+    },
+    delete: {
+        validate: (a) => {
+            const usage = "dss data-collection delete <dataCollectionId> [--dry-run]";
+            requireArgs(a, 1, usage);
+            if (a[0].trim().length === 0) {
+                throw new UsageError(`<dataCollectionId> must be a non-empty identifier. Usage: ${usage}`);
+            }
+        },
+        handler: async (c, a, f) => {
+            if (executionMode(f).dryRun) {
+                return planResult("data-collection", "delete", {
+                    asyncKind: "none",
+                    method: "DELETE",
+                    endpoint: collectionEndpoint(a[0]),
+                    identifiers: { dataCollectionId: a[0], },
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            await c.dataCollections.delete(a[0]);
+            return { deleted: a[0], resource: "data-collection", };
+        },
+        usage: "dss data-collection delete <dataCollectionId> [--dry-run]",
+        description: "Permanently delete a collection. Admin required.",
+        examples: ["dss data-collection delete OjVsTQ3O --dry-run",],
+    },
+    "list-objects": {
+        handler: (c, a) => {
+            requireArgs(a, 1, "dss data-collection list-objects <dataCollectionId>");
+            return c.dataCollections.listObjects(a[0]);
+        },
+        usage: "dss data-collection list-objects <dataCollectionId>",
+        description: "List the objects in a collection.",
+        examples: ["dss data-collection list-objects OjVsTQ3O",],
+    },
+    "add-object": {
+        handler: async (c, a, f) => {
+            const object = requiredJsonInput(f, "--data, --data-file, or --stdin is required (collection object reference).");
+            const collectionId = a[0]
+                ?? (typeof object.dataCollectionId === "string" ? object.dataCollectionId : undefined);
+            if (!collectionId) {
+                throw new UsageError("Usage: dss data-collection add-object <dataCollectionId> (--data JSON|--data-file PATH|--stdin)");
+            }
+            const reference = { ...object, };
+            delete reference.dataCollectionId;
+            if (executionMode(f).dryRun) {
+                return planResult("data-collection", "add-object", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: `${collectionEndpoint(collectionId)}/objects`,
+                    identifiers: { dataCollectionId: collectionId, },
+                    payload: reference,
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            await c.dataCollections.addObject(collectionId, reference);
+            return { added: reference.id, dataCollectionId: collectionId, resource: "data-collection", };
+        },
+        usage: "dss data-collection add-object <dataCollectionId> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
+        description: "Add an object (e.g. {type:'DATASET',projectKey:'K',id:'name'}) to a collection. Contributor required.",
+        examples: [
+            'dss data-collection add-object OjVsTQ3O --data \'{"type":"DATASET","projectKey":"MYPROJECT","id":"orders"}\'',
+        ],
+    },
+    "remove-dataset": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 3, "dss data-collection remove-dataset <dataCollectionId> <projectKey> <datasetName> [--dry-run]");
+            if (executionMode(f).dryRun) {
+                return planResult("data-collection", "remove-dataset", {
+                    asyncKind: "none",
+                    method: "DELETE",
+                    endpoint: `${collectionEndpoint(a[0])}/objects/dataset/${encodeURIComponent(a[1])}/${encodeURIComponent(a[2])}`,
+                    identifiers: {
+                        dataCollectionId: a[0],
+                        projectKey: a[1],
+                        datasetName: a[2],
+                    },
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            await c.dataCollections.removeDataset(a[0], a[1], a[2]);
+            return { removed: a[2], projectKey: a[1], dataCollectionId: a[0], resource: "data-collection", };
+        },
+        usage: "dss data-collection remove-dataset <dataCollectionId> <projectKey> <datasetName> [--dry-run]",
+        description: "Remove a dataset from a collection. Contributor required.",
+        examples: ["dss data-collection remove-dataset OjVsTQ3O MYPROJECT DATASET1",],
+    },
+};

package/dist/src/cli/commands/dataset.js

@@ -1,4 +1,3 @@
-import { buildDatasetCloneSettings, } from "../../resources/datasets.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { compareStrings, stableHash, } from "../../utils/stable-hash.js";
 import { jsonInput, num, schemaColumnsInput, unknownJsonInput, } from "../coerce.js";
@@ -308,43 +307,38 @@ export const datasetCommands = {
         description: "Get dataset-level metadata.",
         examples: ["dss dataset metadata orders",],
     },
-    download: {
+    "metadata-set": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dataset download <name>");
-            const result = await c.datasets.download(a[0], {
-                outputPath: f["output"],
-                projectKey: f["project-key"],
-                limit: num(f["limit"], "--limit"),
-                rawData: f["raw-data"] === true,
-            });
-            if (result.truncated) {
-                enqueueCliWarning({
-                    code: "dataset_download_truncated",
-                    message: `Download of '${a[0]}' stopped at the ${result.limit}-row cap; the dataset has more rows. `
-                        + "Re-run with --limit N for more, or read inside a recipe (get_dataframe) for the full data.",
-                    dataset: a[0],
-                    rows: result.rows,
-                    limit: result.limit,
-                    path: result.path,
-                });
+            const usage = "dss dataset metadata-set <name> (--data JSON | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]";
+            requireArgs(a, 1, usage);
+            // Validated identically for live, --plan, and --dry-run: the JSON
+            // input replaces the server metadata object verbatim (faithful PUT;
+            // no client-side merge).
+            const metadata = jsonInput(f);
+            if (metadata === undefined) {
+                throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${usage}`);
             }
-            if (!f["output"]) {
-                enqueueCliWarning({
-                    code: "dataset_download_default_location",
-                    message: `No --output was given, so '${a[0]}' was written to '${result.path}' in the current directory. `
-                        + "Pass --output PATH to control the destination and avoid writing into your working tree.",
-                    dataset: a[0],
-                    path: result.path,
-                });
+            const pk = f["project-key"];
+            if (executionMode(f).dryRun) {
+                // Zero HTTP: the replacement JSON is validated and echoed as-is;
+                // current server state is intentionally not fetched (faithful
+                // replace means the PUT body is exactly this object).
+                return {
+                    dryRun: true,
+                    action: "metadata-set",
+                    resource: "dataset",
+                    name: a[0],
+                    next: metadata,
+                };
             }
-            return result;
+            const updated = await c.datasets.updateMetadata(a[0], metadata, pk);
+            return { updated: a[0], resource: "dataset", metadata: updated, };
         },
-        usage: "dss dataset download <name> [--output PATH] [--limit N] [--raw-data] [--project-key KEY]",
-        description: "Download up to --limit rows (default 100k) as CSV and return { path, rows, truncated, limit }. Formula-like cells are neutralized for spreadsheets; --raw-data preserves exact bytes. Warnings report truncation and the default output path.",
+        usage: "dss dataset metadata-set <name> (--data JSON | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
+        description: "Replace dataset-level metadata with the given JSON object (faithful PUT: GET, edit, PUT full object; no merge).",
         examples: [
-            "dss dataset download orders",
-            "dss dataset download orders --output ./data/",
-            "dss dataset download orders --raw-data",
+            `dss dataset metadata-set orders --data '{"label":"Orders","tags":["prod"]}' --dry-run`,
+            'echo \'{"label":"Orders"}\' | dss dataset metadata-set orders --stdin',
         ],
     },
     create: {
@@ -396,6 +390,140 @@ export const datasetCommands = {
             "dss dataset create --name orders --connection filesystem --type Filesystem --zone Experiments --dry-run",
         ],
     },
+    "create-managed": {
+        handler: async (c, _a, f) => {
+            const usage = "dss dataset create-managed --name NAME --connection CONN [--type-option-id ID] [--format-option-id ID] [--copy-partitioning-from REF] [--partitioning-folder] [--dry-run] [--project-key KEY]";
+            const name = f["name"];
+            if (!name || name.trim() === "") {
+                throw new UsageError(`--name is required. Usage: ${usage}`);
+            }
+            const connection = f["connection"];
+            if (!connection || connection.trim() === "") {
+                throw new UsageError(`--connection is required. Usage: ${usage}`);
+            }
+            const pk = f["project-key"];
+            // Server-derived settings only: no fabricated defaults are merged in.
+            const payload = {
+                name,
+                connection,
+                ...(typeof f["type-option-id"] === "string" ? { typeOptionId: f["type-option-id"], } : {}),
+                ...(typeof f["format-option-id"] === "string"
+                    ? { formatOptionId: f["format-option-id"], }
+                    : {}),
+                ...(typeof f["copy-partitioning-from"] === "string"
+                    ? {
+                        copyPartitioningFrom: {
+                            ref: f["copy-partitioning-from"],
+                            ...(f["partitioning-folder"] === true ? { type: "FOLDER", } : {}),
+                        },
+                    }
+                    : {}),
+            };
+            if (executionMode(f).dryRun) {
+                return { dryRun: true, action: "create-managed", resource: "dataset", ...payload, };
+            }
+            const created = await c.datasets.createManaged({
+                name,
+                connection,
+                ...(typeof f["type-option-id"] === "string" ? { typeOptionId: f["type-option-id"], } : {}),
+                ...(typeof f["format-option-id"] === "string"
+                    ? { formatOptionId: f["format-option-id"], }
+                    : {}),
+                ...(typeof f["copy-partitioning-from"] === "string"
+                    ? {
+                        copyPartitioningFrom: {
+                            ref: f["copy-partitioning-from"],
+                            ...(f["partitioning-folder"] === true ? { type: "FOLDER", } : {}),
+                        },
+                    }
+                    : {}),
+            }, pk);
+            return {
+                created: created.datasetName,
+                resource: "dataset",
+                managed: true,
+                projectKey: created.projectKey,
+                creationSettings: created.creationSettings,
+            };
+        },
+        usage: "dss dataset create-managed --name NAME --connection CONN [--type-option-id ID] [--format-option-id ID] [--copy-partitioning-from REF] [--partitioning-folder] [--dry-run] [--project-key KEY]",
+        description: "Create a managed dataset via the dedicated endpoint: DSS derives storage/format details; you pick name, connection, and optional type/format/partitioning options.",
+        examples: [
+            "dss dataset create-managed --name orders_copy --connection filesystem_managed",
+            "dss dataset create-managed --name events_parquet --connection s3_conn --format-option-id PARQUET_HIVE --dry-run",
+            "dss dataset create-managed --name partitioned --connection s3_conn --copy-partitioning-from raw_events",
+        ],
+    },
+    info: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss dataset info <name>");
+            return c.datasets.info(a[0], f["project-key"]);
+        },
+        usage: "dss dataset info <name> [--project-key KEY]",
+        description: "Get the full info object for a dataset (type, parameters, last build information, schema, etc.).",
+        examples: ["dss dataset info orders", "dss dataset info orders --project-key MYPROJ",],
+    },
+    "column-lineage": {
+        handler: (c, a, f) => {
+            const usage = "dss dataset column-lineage <name> <column> [--max-dataset-count N] [--project-key KEY]";
+            requireArgs(a, 2, usage);
+            const maxDatasetCount = num(f["max-dataset-count"], "--max-dataset-count");
+            if (maxDatasetCount !== undefined
+                && (!Number.isSafeInteger(maxDatasetCount) || maxDatasetCount <= 0)) {
+                throw new UsageError(`--max-dataset-count must be a positive integer (got "${String(f["max-dataset-count"])}"). `
+                    + `Usage: ${usage}`, "validation_failed");
+            }
+            return c.datasets.getColumnLineage(a[0], a[1], {
+                maxDatasetCount,
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss dataset column-lineage <name> <column> [--max-dataset-count N] [--project-key KEY]",
+        description: "Get the full column lineage (auto-computed and manual) of a column; includes local and foreign project relations.",
+        examples: [
+            "dss dataset column-lineage orders customer_id",
+            "dss dataset column-lineage orders customer_id --max-dataset-count 2000",
+        ],
+    },
+    download: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss dataset download <name>");
+            const result = await c.datasets.download(a[0], {
+                outputPath: f["output"],
+                projectKey: f["project-key"],
+                limit: num(f["limit"], "--limit"),
+                rawData: f["raw-data"] === true,
+            });
+            if (result.truncated) {
+                enqueueCliWarning({
+                    code: "dataset_download_truncated",
+                    message: `Download of '${a[0]}' stopped at the ${result.limit}-row cap; the dataset has more rows. `
+                        + "Re-run with --limit N for more, or read inside a recipe (get_dataframe) for the full data.",
+                    dataset: a[0],
+                    rows: result.rows,
+                    limit: result.limit,
+                    path: result.path,
+                });
+            }
+            if (!f["output"]) {
+                enqueueCliWarning({
+                    code: "dataset_download_default_location",
+                    message: `No --output was given, so '${a[0]}' was written to '${result.path}' in the current directory. `
+                        + "Pass --output PATH to control the destination and avoid writing into your working tree.",
+                    dataset: a[0],
+                    path: result.path,
+                });
+            }
+            return result;
+        },
+        usage: "dss dataset download <name> [--output PATH] [--limit N] [--raw-data] [--project-key KEY]",
+        description: "Download up to --limit rows (default 100k) as CSV and return { path, rows, truncated, limit }. Formula-like cells are neutralized for spreadsheets; --raw-data preserves exact bytes. Warnings report truncation and the default output path.",
+        examples: [
+            "dss dataset download orders",
+            "dss dataset download orders --output ./data/",
+            "dss dataset download orders --raw-data",
+        ],
+    },
     clone: {
         handler: async (c, a, f) => {
             const usage = "dss dataset clone <source> <target> [--path PATH] [--table TABLE] [--metastore-table TABLE] [--allow-same-path] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]";
@@ -409,6 +537,7 @@ export const datasetCommands = {
                 allowSamePath: f["allow-same-path"] === true,
             };
             const current = await c.datasets.get(a[0], pk);
+            const { buildDatasetCloneSettings, } = await import("../../resources/datasets.js");
             const next = buildDatasetCloneSettings(current, a[1], pk ?? c.resolveProjectKey(pk), opts);
             const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
             if (executionMode(f).dryRun) {

package/dist/src/cli/commands/future.js

@@ -39,8 +39,8 @@ export const futureCommands = {
             const id = a[0];
             if (executionMode(f).dryRun) {
                 return planResult("future", "abort", {
-                    method: "POST",
-                    endpoint: `/public/api/futures/${encodeURIComponent(id)}/abort`,
+                    method: "DELETE",
+                    endpoint: `/public/api/futures/${encodeURIComponent(id)}`,
                     identifiers: { id, },
                     idempotency: "none",
                     asyncKind: "future",

package/dist/src/cli/commands/group.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const groupCommands: Record<string, CommandMeta>;

package/dist/src/cli/commands/group.js

@@ -0,0 +1,109 @@
+import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { readIfExists, skipResult, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+/** Group identifiers must be non-empty before any request or dry-run preview. */
+function requireGroupName(value, usage) {
+    const trimmed = value?.trim() ?? "";
+    if (trimmed.length === 0) {
+        throw new UsageError(`group name must be a non-empty string.\nUsage: ${usage}`, "validation_failed");
+    }
+    return trimmed;
+}
+export const groupCommands = {
+    list: {
+        handler: (c) => c.groups.list(),
+        usage: "dss group list",
+        description: "List DSS groups (admin).",
+        examples: ["dss group list",],
+    },
+    get: {
+        handler: (c, a) => {
+            const usage = "dss group get <name>";
+            requireArgs(a, 1, usage);
+            return c.groups.get(requireGroupName(a[0], usage));
+        },
+        usage: "dss group get <name>",
+        description: "Get a DSS group (admin).",
+        examples: ["dss group get administrators",],
+    },
+    create: {
+        handler: async (c, _a, f) => {
+            const usage = "dss group create (--data JSON|--data-file PATH|--stdin)";
+            const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (group definition). Usage: ${usage}`);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "create",
+                    resource: "group",
+                    name: typeof body.name === "string" ? body.name : undefined,
+                    method: "POST",
+                    endpoint: "/public/api/admin/groups",
+                    payload: body,
+                };
+            }
+            return c.groups.create(body);
+        },
+        usage: "dss group create (--data JSON|--data-file PATH|--stdin) [--dry-run]",
+        description: 'Create a DSS group (admin). Body follows the DSS Group schema, e.g. {"name":"analysts","admin":false,"description":"..."}.',
+        examples: [
+            `dss group create --data '{"name":"analysts","admin":false,"description":"Business analysts"}'`,
+        ],
+    },
+    update: {
+        handler: async (c, a, f) => {
+            const usage = "dss group update <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]";
+            requireArgs(a, 1, usage);
+            const name = requireGroupName(a[0], usage);
+            const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (group definition). Usage: ${usage}`);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "update",
+                    resource: "group",
+                    name,
+                    method: "PUT",
+                    endpoint: `/public/api/admin/groups/${encodeURIComponent(name)}`,
+                    payload: body,
+                    note: "PUT replaces the whole Group object; the body must come from `dss group get`. No GET was issued in dry-run.",
+                };
+            }
+            await c.groups.update(name, body);
+            return { updated: name, };
+        },
+        usage: "dss group update <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
+        description: "Update a DSS group (admin). The body MUST be the Group object obtained from `dss group get` (PUT semantics); pass undocumented attributes through unchanged. Use --dry-run to preview the merged result without writing.",
+        examples: [
+            `dss group update analysts --data '{"name":"ANALYSTS","admin":false,"description":"Business analysts"}'`,
+        ],
+    },
+    delete: {
+        handler: async (c, a, f) => {
+            const usage = "dss group delete <name> [--if-exists] [--dry-run]";
+            requireArgs(a, 1, usage);
+            const name = requireGroupName(a[0], usage);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "delete",
+                    resource: "group",
+                    name,
+                    method: "DELETE",
+                    endpoint: `/public/api/admin/groups/${encodeURIComponent(name)}`,
+                    ...(f["if-exists"] === true
+                        ? { note: "Existence not checked in dry-run; live --if-exists issues a GET probe first.", }
+                        : {}),
+                };
+            }
+            if (f["if-exists"] === true) {
+                const current = await readIfExists(() => c.groups.get(name));
+                if (!current)
+                    return skipResult("group", name, "missing");
+            }
+            return c.groups.delete(name);
+        },
+        usage: "dss group delete <name> [--if-exists] [--dry-run]",
+        description: "Delete a DSS group (admin). Destructive and irreversible.",
+        examples: ["dss group delete analysts", "dss group delete analysts --if-exists",],
+    },
+};