dataiku-sdk 3.7.0 → 3.8.0

package/dist/src/cli/flags.d.ts

@@ -18,6 +18,13 @@ export declare const REPEATABLE_VALUE_FLAGS: Set<string>;
 export declare const KNOWN_LONG_FLAGS: Set<string>;
 export declare function normalizeLongFlag(rawFlagName: string, argv: string[]): string;
 export declare function isNegativeNumberToken(value: string): boolean;
+/**
+ * Whether the token after a value flag is that flag's value rather than the
+ * next flag. `-` (stdin), negative numbers, and anything not flag-shaped
+ * qualify, so a SQL value beginning with a `-- comment` is a value; `--` alone
+ * and `--flag`/`--flag=x` are not.
+ */
+export declare function isFlagValueToken(token: string): boolean;
 export declare function requireFlagValue(flagLabel: string, next: string | undefined): string;
 export declare function setParsedFlagValue(flags: Record<string, string | boolean>, flagName: string, value: string): void;
 export interface ParsedArgs {

package/dist/src/cli/flags.js

@@ -81,6 +81,7 @@ export const BOOLEAN_FLAGS = new Set([
     "allow-same-path",
     "sync",
     "validate-objects",
+    "recreate-on-move",
     "errors-only",
     "keep",
     "full-log",
@@ -223,6 +224,8 @@ export const VALUE_FLAGS = new Set([
     "render",
     "prediction-type",
     "project-key",
+    "query",
+    "query-file",
     "recipe",
     "reference",
     "repository",
@@ -353,9 +356,32 @@ export function normalizeLongFlag(rawFlagName, argv) {
 export function isNegativeNumberToken(value) {
     return value.startsWith("-") && Number.isFinite(Number(value));
 }
+/** `--name` or `--name=value`: a token that parses as a long flag. */
+const LONG_FLAG_SHAPE = /^--[A-Za-z][A-Za-z0-9-]*(?:=|$)/;
+/**
+ * Whether the token after a value flag is that flag's value rather than the
+ * next flag. `-` (stdin), negative numbers, and anything not flag-shaped
+ * qualify, so a SQL value beginning with a `-- comment` is a value; `--` alone
+ * and `--flag`/`--flag=x` are not.
+ */
+export function isFlagValueToken(token) {
+    if (token === "-" || isNegativeNumberToken(token))
+        return true;
+    if (!token.startsWith("-"))
+        return true;
+    return token.startsWith("--") && token !== "--" && !LONG_FLAG_SHAPE.test(token);
+}
 export function requireFlagValue(flagLabel, next) {
-    if (next === undefined || (next !== "-" && next.startsWith("-") && !isNegativeNumberToken(next))) {
-        throw new UsageError(`Flag ${flagLabel} requires a value.`, "missing_required_flag");
+    if (next === undefined || !isFlagValueToken(next)) {
+        const inlineForm = flagLabel.startsWith("--") ? `${flagLabel}=VALUE` : undefined;
+        const hint = next === undefined || !next.startsWith("-")
+            ? undefined
+            : flagLabel === "--sql"
+                ? 'A SQL value that starts with `--` (a comment) can be passed as --sql="-- ...", from a file with --sql-file PATH, or on stdin with --stdin.'
+                : inlineForm
+                    ? `If the value itself starts with \`-\`, pass it as ${inlineForm}.`
+                    : undefined;
+        throw new UsageError(`Flag ${flagLabel} requires a value.`, "missing_required_flag", hint);
     }
     return next;
 }

package/dist/src/cli/helpers/dataset.d.ts

@@ -1,2 +1,14 @@
 import type { DatasetDetails } from "../../schemas.js";
+export interface DatasetSqlSourceFlags {
+    table?: string;
+    dbSchema?: string;
+    catalog?: string;
+    query?: string;
+}
+/**
+ * The SQL source of `dataset create` (`--table [--schema S] [--catalog C]` or
+ * `--query SQL`/`--query-file PATH`), validated against the dataset type.
+ * Empty when no SQL flag is given.
+ */
+export declare function datasetSqlSourceFromFlags(flags: Record<string, string | boolean>, dsType: string): DatasetSqlSourceFlags;
 export declare function datasetSourceSummary(details: DatasetDetails): Record<string, unknown>;

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

@@ -1,3 +1,39 @@
+import { assertSqlDatasetSource, } from "../../resources/dataset-create.js";
+import { readInputText, stripUtf8Bom, } from "../coerce.js";
+import { UsageError, } from "../usage.js";
+/**
+ * The SQL source of `dataset create` (`--table [--schema S] [--catalog C]` or
+ * `--query SQL`/`--query-file PATH`), validated against the dataset type.
+ * Empty when no SQL flag is given.
+ */
+export function datasetSqlSourceFromFlags(flags, dsType) {
+    const text = (flag) => {
+        const value = flags[flag];
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== "string") {
+            throw new UsageError(`--${flag} requires a value.`, "missing_required_flag");
+        }
+        return value;
+    };
+    if (flags["query"] !== undefined && flags["query-file"] !== undefined) {
+        throw new UsageError("Conflicting input sources: --query, --query-file. Provide exactly one.", "conflicting_input_sources", undefined, { sources: ["query", "query-file",], });
+    }
+    const queryFile = text("query-file");
+    const inline = text("query");
+    const source = {
+        ...(text("table") !== undefined ? { table: text("table"), } : {}),
+        ...(text("schema") !== undefined ? { dbSchema: text("schema"), } : {}),
+        ...(text("catalog") !== undefined ? { catalog: text("catalog"), } : {}),
+        ...(queryFile !== undefined
+            ? { query: stripUtf8Bom(readInputText(queryFile, "--query-file")), }
+            : inline !== undefined
+                ? { query: inline, }
+                : {}),
+    };
+    assertSqlDatasetSource(dsType, source);
+    return source;
+}
 export function datasetSourceSummary(details) {
     const params = details.params ?? {};
     return {

package/dist/src/cli/helpers/flow-zone.d.ts

@@ -1,6 +1,7 @@
 import type { DataikuClient } from "../../client.js";
 import type { FlowZoneItemInput } from "../../resources/flow-zones.js";
 import type { FlowZone, FlowZoneObjectType, FlowZonePosition } from "../../schemas.js";
+import type { NormalizedFlowMap } from "../../utils/flow-map.js";
 export declare function flowZoneId(value: string): string;
 export declare function flowZoneName(value: string | boolean | undefined): string;
 export declare function flowZoneColor(value: string | boolean | undefined): string | undefined;
@@ -18,6 +19,8 @@ export interface FlowZoneOrganizeZonePlan {
     color?: string;
     position?: FlowZonePosition;
     items: FlowZoneItemInput[];
+    /** Recipe/output unit members added by {@link applyFlowZoneUnits}; also present in `items`. */
+    impliedItems?: FlowZoneItemInput[];
 }
 export interface FlowZoneOrganizePlan {
     topologyFingerprint?: string;
@@ -60,7 +63,25 @@ export declare function flowZoneExplicitItems(zone: FlowZone): FlowZoneItemInput
 export declare function flowZonePlanFromZones(zones: FlowZone[], topologyFingerprint: string): FlowZoneOrganizePlan;
 export declare function flowZoneMoveDelta(existing: FlowZone | undefined, plannedItems: FlowZoneItemInput[]): FlowZoneItemInput[];
 export declare function flowZonePruneItems(existing: FlowZone | undefined, plannedItemKeys: Set<string>): FlowZoneItemInput[];
+/**
+ * The position an existing zone must move to, if the plan changes it. DSS
+ * honors a zone position only on creation, so a move means recreating the zone.
+ */
+export declare function flowZoneRepositionTarget(plan: FlowZoneOrganizeZonePlan, existing: FlowZone): FlowZonePosition | undefined;
 export declare function flowZoneOrganizeStep(plan: FlowZoneOrganizeZonePlan, existing: FlowZone | undefined, sync: boolean, plannedItemKeys: Set<string>): Record<string, unknown>;
+/**
+ * Enforce the DSS recipe/output zone invariant on a plan. Rejects plans that
+ * place members of one unit in different zones (they would never converge),
+ * and adds the unlisted members of each planned unit to that zone as
+ * `impliedItems`, so moves, `--sync` pruning, and reruns all agree with what
+ * DSS actually does.
+ */
+export declare function applyFlowZoneUnits(plan: FlowZoneOrganizePlan, graph: NormalizedFlowMap, zones: FlowZone[], projectKey: string | undefined): FlowZoneOrganizePlan;
+/**
+ * Default-zone objects an organization plan has to place: recipes (their
+ * outputs follow) and objects no recipe produces, such as uploaded sources.
+ */
+export declare function flowZoneUnassignedItems(graph: NormalizedFlowMap, zones: FlowZone[]): FlowZoneItemInput[];
 export declare function flowZoneValidationBucket(index: FlowZoneOrganizeValidationIndex, objectType: FlowZoneObjectType): Set<string>;
 export declare function flowZoneValidationIndex(client: DataikuClient, projectKey: string | undefined): Promise<FlowZoneOrganizeValidationIndex>;
 export declare function validateFlowZoneOrganizeObjects(client: DataikuClient, plan: FlowZoneOrganizePlan, projectKey: string | undefined): Promise<FlowZoneOrganizeValidationResult>;

package/dist/src/cli/helpers/flow-zone.js

@@ -1,4 +1,5 @@
 import { readFileSync, } from "node:fs";
+import { ClientValidationError, } from "../../errors.js";
 import { asRecord, } from "../../utils/records.js";
 import { compareStrings, } from "../../utils/stable-hash.js";
 import { finiteNumberField, jsonInput, optionalStringField, parseJsonObject, requiredStringArray, splitCsvFlag, } from "../coerce.js";
@@ -319,6 +320,16 @@ export function flowZonePruneItems(existing, plannedItemKeys) {
         return [];
     return flowZoneExplicitItems(existing).filter((item) => !plannedItemKeys.has(flowZoneItemKey(item)));
 }
+/**
+ * The position an existing zone must move to, if the plan changes it. DSS
+ * honors a zone position only on creation, so a move means recreating the zone.
+ */
+export function flowZoneRepositionTarget(plan, existing) {
+    return plan.position !== undefined
+        && !flowZoneSamePosition(flowZoneCurrentPosition(existing), plan.position)
+        ? plan.position
+        : undefined;
+}
 export function flowZoneOrganizeStep(plan, existing, sync, plannedItemKeys) {
     ensureFlowZonePlanTarget(plan, existing);
     const update = {};
@@ -326,10 +337,8 @@ export function flowZoneOrganizeStep(plan, existing, sync, plannedItemKeys) {
         update.name = plan.name;
     if (existing && plan.color && plan.color !== existing.color)
         update.color = plan.color;
-    if (existing && plan.position !== undefined
-        && !flowZoneSamePosition(flowZoneCurrentPosition(existing), plan.position)) {
-        update.position = plan.position;
-    }
+    const recreatePosition = existing ? flowZoneRepositionTarget(plan, existing) : undefined;
+    const recreate = recreatePosition ? { position: recreatePosition, } : undefined;
     const pruneItems = sync ? flowZonePruneItems(existing, plannedItemKeys) : [];
     const moveItems = flowZoneMoveDelta(existing, plan.items);
     return {
@@ -341,10 +350,141 @@ export function flowZoneOrganizeStep(plan, existing, sync, plannedItemKeys) {
         },
         ...(existing ? { existing: flowZoneSummary(existing), } : { create: true, }),
         ...(Object.keys(update).length > 0 ? { update, } : {}),
+        ...(recreate ? { recreate, } : {}),
         moveItems,
+        ...(plan.impliedItems && plan.impliedItems.length > 0
+            ? { impliedItems: plan.impliedItems, }
+            : {}),
         ...(pruneItems.length > 0 ? { pruneItems, } : {}),
     };
 }
+function flowNodeObjectType(node, knownTypes) {
+    switch (node.kind) {
+        case "recipe":
+            return "RECIPE";
+        case "dataset":
+            return "DATASET";
+        case "folder":
+            return "MANAGED_FOLDER";
+        default:
+            return knownTypes.get(node.id);
+    }
+}
+/**
+ * DSS keeps a recipe and its outputs in one zone: moving either drags the
+ * others. Each unit is keyed by its recipe id and lists the recipe plus every
+ * object the recipe writes.
+ */
+function flowZoneUnits(graph) {
+    const kindById = new Map(graph.nodes.map((node) => [node.id, node.kind,]));
+    const units = new Map();
+    for (const node of graph.nodes) {
+        if (node.kind === "recipe")
+            units.set(node.id, [node.id,]);
+    }
+    for (const edge of graph.edges) {
+        if (kindById.get(edge.from) !== "recipe" || kindById.get(edge.to) === "recipe")
+            continue;
+        units.get(edge.from)?.push(edge.to);
+    }
+    return units;
+}
+function explicitTypesById(zones) {
+    const types = new Map();
+    for (const zone of zones) {
+        for (const item of flowZoneItems(zone)) {
+            if (!item.projectKey)
+                types.set(item.objectId, item.objectType);
+        }
+    }
+    return types;
+}
+/**
+ * Enforce the DSS recipe/output zone invariant on a plan. Rejects plans that
+ * place members of one unit in different zones (they would never converge),
+ * and adds the unlisted members of each planned unit to that zone as
+ * `impliedItems`, so moves, `--sync` pruning, and reruns all agree with what
+ * DSS actually does.
+ */
+export function applyFlowZoneUnits(plan, graph, zones, projectKey) {
+    const zoneIndexById = new Map();
+    plan.zones.forEach((zonePlan, index) => {
+        for (const item of zonePlan.items) {
+            // Shared objects from other projects never move with a local recipe.
+            if (!item.projectKey || item.projectKey === projectKey)
+                zoneIndexById.set(item.objectId, index);
+        }
+    });
+    const nodeById = new Map(graph.nodes.map((node) => [node.id, node,]));
+    const knownTypes = explicitTypesById(zones);
+    const conflicts = [];
+    const implied = plan.zones.map(() => []);
+    for (const [recipe, members,] of flowZoneUnits(graph)) {
+        const planned = members.filter((member) => zoneIndexById.has(member));
+        if (planned.length === 0)
+            continue;
+        const indexes = new Set(planned.map((member) => zoneIndexById.get(member)));
+        if (indexes.size > 1) {
+            const byZone = {};
+            for (const member of planned) {
+                const label = flowZonePlanLabel(plan.zones[zoneIndexById.get(member)]);
+                (byZone[label] ??= []).push(member);
+            }
+            conflicts.push({ recipe, zones: byZone, });
+            continue;
+        }
+        const [index,] = indexes;
+        for (const member of members) {
+            if (zoneIndexById.has(member))
+                continue;
+            const node = nodeById.get(member);
+            const objectType = node ? flowNodeObjectType(node, knownTypes) : undefined;
+            if (objectType)
+                implied[index].push({ objectType, objectId: member, });
+        }
+    }
+    if (conflicts.length > 0) {
+        throw new ClientValidationError(`Flow zone plan splits ${conflicts.length} recipe(s) from their outputs across zones; DSS keeps a recipe and its outputs in one zone.`, "validation_failed", "Assign each recipe to one zone (its outputs follow automatically), or list the recipe and all its outputs in the same zone.", { conflicts, });
+    }
+    return {
+        ...plan,
+        zones: plan.zones.map((zonePlan, index) => implied[index].length === 0
+            ? zonePlan
+            : {
+                ...zonePlan,
+                items: [...zonePlan.items, ...implied[index],],
+                impliedItems: implied[index],
+            }),
+    };
+}
+/**
+ * Default-zone objects an organization plan has to place: recipes (their
+ * outputs follow) and objects no recipe produces, such as uploaded sources.
+ */
+export function flowZoneUnassignedItems(graph, zones) {
+    const assigned = new Set();
+    for (const zone of zones) {
+        if (zone.id === "default")
+            continue;
+        for (const item of flowZoneExplicitItems(zone))
+            assigned.add(item.objectId);
+    }
+    const produced = new Set();
+    for (const members of flowZoneUnits(graph).values()) {
+        for (const member of members.slice(1))
+            produced.add(member);
+    }
+    const knownTypes = explicitTypesById(zones);
+    const items = [];
+    for (const node of graph.nodes) {
+        if (assigned.has(node.id) || produced.has(node.id))
+            continue;
+        const objectType = flowNodeObjectType(node, knownTypes);
+        if (objectType)
+            items.push({ objectType, objectId: node.id, });
+    }
+    return items.sort((a, b) => compareStrings(flowZoneItemKey(a), flowZoneItemKey(b)));
+}
 export function flowZoneValidationBucket(index, objectType) {
     switch (objectType) {
         case "DATASET":

package/dist/src/cli/output.js

@@ -187,6 +187,12 @@ export class CommandResultFailure extends Error {
 export function commandFailureMessage(result) {
     if (isFailedWaitResult(result)) {
         const record = result;
+        const failure = record.failure;
+        if (failure !== null && typeof failure === "object" && !Array.isArray(failure)) {
+            const message = failure.message;
+            if (typeof message === "string" && message.length > 0)
+                return message;
+        }
         const state = typeof record.state === "string"
             ? record.state
             : typeof record.outcome === "string"

package/dist/src/cli/plans.js

@@ -16,11 +16,12 @@ import { schemaPropagationOptionsFromFlags, } from "./commands/flow.js";
 import { mlTaskFieldsFromFlags, mlTaskReguessOptionsFromFlags, } from "./commands/ml-task.js";
 import { deployRunOptionsFromFlags, experimentsDatasetOptionsFromFlags, inferenceInfoFromFlags, } from "./commands/mlflow.js";
 import { projectLibraryPutPayload, } from "./commands/project-library.js";
-import { recipeCreateOptionsFromFlags, } from "./commands/recipe.js";
+import { enqueueRecipeCreateWarnings, recipeCreateOptionsFromFlags, } from "./commands/recipe.js";
 import { resolveSqlQueryInvocation, } from "./commands/sql.js";
 import { buildRegistryEntry, splitPackageSpec, } from "./contract.js";
 import { ambientProjectKey, } from "./env.js";
 import { executionMode, } from "./flags.js";
+import { datasetSqlSourceFromFlags, } from "./helpers/dataset.js";
 import { flowZoneColor, flowZoneMoveItems, flowZoneName, } from "./helpers/flow-zone.js";
 import { recipeBackupPath, recipeRunShouldWait, } from "./helpers/recipe.js";
 import { diagnosticsComputationFromFlags, } from "./helpers/trained-model.js";
@@ -419,6 +420,50 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 endpoint: projectEndpoint(`/wiki/${encodeURIComponent(id)}`),
                 identifiers: { article: id, },
             };
+        case "wiki.attach": {
+            const articleEndpoint = projectEndpoint(`/wiki/${encodeURIComponent(id)}`);
+            const upload = {
+                method: "POST",
+                endpoint: `${articleEndpoint}/upload`,
+                payload: uploadPayload(args[1]),
+            };
+            return {
+                ...upload,
+                identifiers: { article: id, localPath: args[1], },
+                requests: [
+                    {
+                        sequence: 1,
+                        method: "GET",
+                        endpoint: articleEndpoint,
+                        purpose: "read current attachments",
+                    },
+                    { sequence: 2, ...upload, },
+                    {
+                        sequence: 3,
+                        method: "GET",
+                        endpoint: articleEndpoint,
+                        assert: { newAttachments: 1, },
+                    },
+                ],
+            };
+        }
+        case "wiki.detach": {
+            const articleEndpoint = projectEndpoint(`/wiki/${encodeURIComponent(id)}`);
+            return {
+                method: "PUT",
+                endpoint: articleEndpoint,
+                identifiers: { article: id, smartId: args[1], },
+                requests: [
+                    { sequence: 1, method: "GET", endpoint: articleEndpoint, },
+                    {
+                        sequence: 2,
+                        method: "PUT",
+                        endpoint: articleEndpoint,
+                        payload: "<article data without the attachment with the given smartId>",
+                    },
+                ],
+            };
+        }
         case "dashboard.create": {
             const data = jsonInput(flags);
             const flagName = flags["name"];
@@ -730,8 +775,16 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             if (!connection && dsType.toLowerCase() !== "uploadedfiles") {
                 throw new UsageError("--connection is required unless --type is UploadedFiles.");
             }
+            const sqlSource = datasetSqlSourceFromFlags(flags, dsType);
+            const hasSqlSource = sqlSource.table !== undefined || sqlSource.query !== undefined;
             const endpoint = projectEndpoint("/datasets/"); // throws without a project key
             return {
+                ...(hasSqlSource
+                    ? {
+                        exact: false,
+                        reason: "The POST is exact; apply then detects the schema (POST /actions/testAndDetectSettings/externalSQL) and stores it (PUT /schema).",
+                    }
+                    : {}),
                 method: "POST",
                 endpoint,
                 identifiers: { name, },
@@ -740,6 +793,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     datasetName: name,
                     connection,
                     dsType,
+                    ...sqlSource,
                 }),
             };
         }
@@ -924,7 +978,9 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             }
             const endpoint = projectEndpoint("/recipes/"); // throws without a project key
             // Same flag mapping and body construction as the handler and RecipesResource.create.
-            const { recipePrototype, creationSettings, grouping, prepareSteps, } = buildRecipeCreateRequest(recipeCreateOptionsFromFlags(flags), projectKey);
+            const createOptions = recipeCreateOptionsFromFlags(flags);
+            enqueueRecipeCreateWarnings(createOptions);
+            const { recipePrototype, creationSettings, grouping, prepareSteps, } = buildRecipeCreateRequest(createOptions, projectKey);
             const edits = grouping
                 ? { grouping, }
                 : prepareSteps.length > 0

package/dist/src/cli/types.d.ts

@@ -7,6 +7,8 @@ export interface CommandPayloadSchema {
     dataFileFlag?: boolean;
     contentType?: "application/json" | "text/plain";
     jsonShape?: "object" | "array";
+    /** Precise JSON Schema of the payload, published as the contract's `schemas.input`. */
+    jsonSchema?: Record<string, unknown>;
 }
 export interface CommandFlagChoice {
     oneOf: string[][];

package/dist/src/cli.js

@@ -5,7 +5,7 @@ import { resolve, } from "node:path";
 import { num, seenJsonInputCredentials, unknownJsonInput, } from "./cli/coerce.js";
 import { commands, } from "./cli/commands/index.js";
 import { ambientProjectKey, loadEnvFile, } from "./cli/env.js";
-import { executionMode, FLAG_ALIASES, isNegativeNumberToken, parseArgs, rawPositionals, } from "./cli/flags.js";
+import { executionMode, FLAG_ALIASES, isFlagValueToken, parseArgs, rawPositionals, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
 import { shapeListResult, } from "./cli/list-output.js";
 import { commandFailureExitCode, CommandResultFailure, enqueueCliWarning, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
@@ -533,8 +533,7 @@ function redactArgv(argv) {
                 else {
                     redacted.push(arg);
                     const next = argv[index + 1];
-                    if (next !== undefined
-                        && (next === "-" || !next.startsWith("-") || isNegativeNumberToken(next))) {
+                    if (next !== undefined && isFlagValueToken(next)) {
                         redacted.push("***");
                         index++;
                     }
@@ -1247,6 +1246,10 @@ function dssDiagnosticDetails(err) {
 function isAmbiguousMutationFailure(err, context) {
     if (!(err instanceof DataikuError))
         return false;
+    // DSS definitively refused the operation (e.g. the database rejected the SQL):
+    // nothing took effect, so there is no outcome to verify.
+    if (err.definiteFailure)
+        return false;
     const method = err.retry?.method.toUpperCase();
     if (!method || method === "GET" || method === "HEAD")
         return false;
@@ -1363,6 +1366,7 @@ function buildErrorReport(err, contextOverride) {
                 idempotency: "none",
                 ...dssErrorDetails(err),
                 ...dssDiagnosticDetails(err),
+                ...err.details,
                 ...(err.retry ? { retry: err.retry, } : {}),
             },
             ...context,
@@ -1370,7 +1374,11 @@ function buildErrorReport(err, contextOverride) {
     }
     if (err instanceof DataikuError) {
         const { dssMessage, dssErrorType, } = dssDiagnosticDetails(err);
-        const details = { ...dssErrorDetails(err), ...(dssErrorType ? { dssErrorType, } : {}), };
+        const details = {
+            ...dssErrorDetails(err),
+            ...(dssErrorType ? { dssErrorType, } : {}),
+            ...err.details,
+        };
         // Generic hints name what the command targeted. DSS answers 403 (not
         // 404) for a project that does not exist: "Failed to read project
         // permissions". A 403 about something else keeps the generic hint.

package/dist/src/errors.d.ts

@@ -20,12 +20,18 @@ export interface DataikuErrorTrustedMetadata {
     elapsedMs?: number;
     /** Set by the transport when the retained response body is only a bounded prefix. */
     bodyTruncated?: boolean;
+    /**
+     * Set by a resource that recognized DSS's answer as a definite failure of the
+     * whole operation: nothing took effect, so a non-idempotent mutation is not
+     * ambiguous.
+     */
+    definiteFailure?: boolean;
 }
 export declare function canonicalStatusText(status: number): string;
 export declare class ClientValidationError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;
-    readonly details?: Record<string, unknown>;
+    details?: Record<string, unknown>;
     constructor(message: string, code?: StableErrorCode, hint?: string, details?: Record<string, unknown>, options?: ErrorOptions);
 }
 /**
@@ -62,6 +68,10 @@ export declare class DataikuError extends Error {
     readonly trustedTarget?: string;
     readonly trustedElapsedMs?: number;
     readonly bodyTruncated?: boolean;
+    /** DSS definitively failed the whole operation; see `DataikuErrorTrustedMetadata.definiteFailure`. */
+    readonly definiteFailure?: boolean;
+    /** Client-side outcome context (e.g. rollback of partial mutations), surfaced in CLI `details`. */
+    details?: Record<string, unknown>;
     constructor(status: number, statusText: string, body: string, retry?: DataikuRetryMetadata, requestId?: string, trustedMetadata?: DataikuErrorTrustedMetadata);
     /** Status line only: never echoes response body text. */
     get safeMessage(): string;

package/dist/src/errors.js

@@ -74,6 +74,8 @@ export const UNEXPECTED_RESPONSE_MARKER = "Unexpected DSS response";
 export function unexpectedResponseError(detail, status = 200) {
     return new DataikuError(status, "Unexpected Response", `${UNEXPECTED_RESPONSE_MARKER}: ${detail}`);
 }
+/** Hint for a DSS answer that definitively failed the request (e.g. the database rejected the SQL). */
+const DEFINITE_FAILURE_HINT = "DSS reported that the request failed (for SQL: syntax error, missing object, or missing privileges of the connection's role). Fix the request or grants; do not retry unchanged.";
 /** Prefix for a SQL query failure reported by DSS on a 2xx finish-streaming response. */
 export const SQL_QUERY_FAILED_MARKER = "SQL query failed in DSS";
 const TLS_CERTIFICATE_HINT = "TLS certificate verification failed. Trust the DSS/corporate CA with --ca-cert PATH or NODE_EXTRA_CA_CERTS, or save it for every process and directory with `dss auth login --ca-cert PATH` (a project .env applies only when dss runs in that directory); use --insecure only for temporary troubleshooting.";
@@ -140,6 +142,8 @@ function isCertificateTrustFailure(lowerBody) {
         || lowerBody.includes("unable to get local issuer certificate")
         || lowerBody.includes("unable to verify leaf signature")
         || lowerBody.includes("self-signed certificate")
+        || lowerBody.includes("self signed certificate")
+        || lowerBody.includes("depth_zero_self_signed_cert")
         || lowerBody.includes("certificate has expired")
         || lowerBody.includes("cert_has_expired")
         || lowerBody.includes("self_signed_cert_in_chain")
@@ -372,6 +376,10 @@ export class DataikuError extends Error {
     trustedTarget;
     trustedElapsedMs;
     bodyTruncated;
+    /** DSS definitively failed the whole operation; see `DataikuErrorTrustedMetadata.definiteFailure`. */
+    definiteFailure;
+    /** Client-side outcome context (e.g. rollback of partial mutations), surfaced in CLI `details`. */
+    details;
     constructor(status, statusText, body, retry, requestId, trustedMetadata) {
         const details = DataikuError.buildDetails(status, body);
         super(details.message);
@@ -379,14 +387,21 @@ export class DataikuError extends Error {
         this.statusText = statusText;
         this.body = body;
         this.name = "DataikuError";
-        this.category = details.category;
-        this.retryable = details.retryable;
-        this.retryHint = details.retryHint;
+        const definite = trustedMetadata?.definiteFailure === true;
+        // A definite DSS refusal is not a transport/server fault: replaying it
+        // unchanged cannot succeed. Keep a more specific forbidden/not_found class.
+        const reclassify = definite
+            && (details.category === "transient" || details.category === "unknown"
+                || details.category === "unexpected_response");
+        this.category = reclassify ? "validation" : details.category;
+        this.retryable = reclassify ? false : details.retryable;
+        this.retryHint = reclassify ? DEFINITE_FAILURE_HINT : details.retryHint;
         this.retry = retry;
         this.requestId = requestId;
         this.trustedTarget = trustedMetadata?.target;
         this.trustedElapsedMs = trustedMetadata?.elapsedMs;
         this.bodyTruncated = trustedMetadata?.bodyTruncated === true ? true : undefined;
+        this.definiteFailure = definite ? true : undefined;
     }
     /** Status line only: never echoes response body text. */
     get safeMessage() {

package/dist/src/resources/dataset-create.d.ts

@@ -4,6 +4,24 @@
  * public endpoint writes; without it every downstream build fails.
  */
 export declare function assertDatasetTypeCreatable(dsType: string): void;
+/**
+ * Dataset types that read from a SQL connection. These are the types DSS
+ * detects schemas for through `testAndDetectSettings/externalSQL` (the list
+ * dataikuapi's `DSSDataset.autodetect_settings` uses).
+ */
+export declare const SQL_DATASET_TYPES: readonly ["JDBC", "PostgreSQL", "MySQL", "Vertica", "Snowflake", "Redshift", "Greenplum", "Teradata", "Oracle", "SQLServer", "SAPHANA", "Netezza", "BigQuery", "Athena", "hiveserver2", "Synapse", "FabricWarehouse", "Databricks", "DatabricksLakebase"];
+export declare function isSqlDatasetType(dsType: string): boolean;
+/**
+ * Validate the SQL source options (`table`/`dbSchema`/`catalog`/`query`) of a
+ * dataset creation against its type. Shared by `dataset create`, its plan, and
+ * the SDK so every entry point rejects the same combinations.
+ */
+export declare function assertSqlDatasetSource(dsType: string, source: {
+    table?: string;
+    dbSchema?: string;
+    catalog?: string;
+    query?: string;
+}): void;
 /** Wire body for POST /datasets/; shared with `dataset create --plan` so the plan matches the request. */
 export declare function buildDatasetCreateBody(opts: {
     projectKey: string;
@@ -13,6 +31,7 @@ export declare function buildDatasetCreateBody(opts: {
     table?: string;
     dbSchema?: string;
     catalog?: string;
+    query?: string;
     formatType?: string;
     formatParams?: Record<string, unknown>;
     managed?: boolean;