@kweaver-ai/kweaver-sdk 0.7.2 → 0.7.4

package/dist/commands/bkn-metric.js

@@ -0,0 +1,406 @@
+import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
+import { listMetrics, createMetrics, searchMetrics, validateMetrics, getMetric, updateMetric, deleteMetric, getMetrics, deleteMetrics, } from "../api/bkn-metrics.js";
+import { metricQueryData, metricDryRun } from "../api/ontology-query-metrics.js";
+import { formatCallOutput } from "./call.js";
+import { resolveBusinessDomain } from "../config/store.js";
+import { parseJsonObject, parseSearchAfterArray, confirmYes } from "./bkn-utils.js";
+function parseCommaSeparatedIds(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+const METRIC_HELP = `kweaver bkn metric <action> [args] [--pretty] [-bd <domain>]
+
+Management (bkn-backend):
+  list <kn-id> [--limit <n>] [--branch <b>] [--name-pattern <p>] [--sort update_time|name] [--direction asc|desc] [--offset <n>] [--tag <t>] [--group-id <id>]
+  get <kn-id> <metric-id(s)> [--branch <b>]   (comma-separated for multiple)
+  create <kn-id> '<json>'  [--branch] [--strict-mode true|false]
+  search <kn-id> '<json>'  [--branch] [--strict-mode] [--limit <n>] [--search-after '<json>']
+  validate <kn-id> '<json>'  [--branch] [--strict-mode] [--import-mode normal|ignore|overwrite]
+  update <kn-id> <metric-id> '<json>'  [--branch] [--strict-mode]
+  delete <kn-id> <metric-id(s)> [-y]   (comma-separated for multiple)
+
+Query (ontology-query):
+  query <kn-id> <metric-id> ['<json-body>']  [--branch] [--fill-null]
+  dry-run <kn-id> '<json>'  [--branch] [--fill-null]
+
+  list: default --limit 30. search/query JSON: default limit 50 in body when not set.`;
+function parseListArgs(args) {
+    let pretty = true;
+    let businessDomain = "";
+    let limit = 30;
+    let branch;
+    let namePattern;
+    let sort;
+    let direction;
+    let offset;
+    let tag;
+    let groupId;
+    const pos = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--help" || a === "-h")
+            throw new Error("help");
+        if (a === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if ((a === "-bd" || a === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--limit" && args[i + 1]) {
+            const n = parseInt(args[i + 1], 10);
+            if (Number.isNaN(n) || n < 1)
+                throw new Error("Invalid --limit");
+            limit = n;
+            i += 1;
+            continue;
+        }
+        if (a === "--branch" && args[i + 1]) {
+            branch = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--name-pattern" && args[i + 1]) {
+            namePattern = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--sort" && args[i + 1]) {
+            const s = args[i + 1];
+            if (s !== "update_time" && s !== "name")
+                throw new Error("--sort must be update_time|name");
+            sort = s;
+            i += 1;
+            continue;
+        }
+        if (a === "--direction" && args[i + 1]) {
+            const d = args[i + 1];
+            if (d !== "asc" && d !== "desc")
+                throw new Error("--direction must be asc|desc");
+            direction = d;
+            i += 1;
+            continue;
+        }
+        if (a === "--offset" && args[i + 1]) {
+            offset = parseInt(args[i + 1], 10);
+            i += 1;
+            continue;
+        }
+        if (a === "--tag" && args[i + 1]) {
+            tag = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--group-id" && args[i + 1]) {
+            groupId = args[i + 1];
+            i += 1;
+            continue;
+        }
+        pos.push(a);
+    }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    const [knId] = pos;
+    if (!knId)
+        throw new Error("Usage: kweaver bkn metric list <kn-id> [options]");
+    return {
+        knId,
+        limit,
+        pretty,
+        businessDomain,
+        branch,
+        namePattern,
+        sort,
+        direction,
+        offset,
+        tag,
+        groupId,
+    };
+}
+function parseCommonKnFlags(rest, withYes) {
+    let pretty = true;
+    let businessDomain = "";
+    let branch;
+    let strictMode;
+    let importMode;
+    let fillNull;
+    let yes = false;
+    const out = [];
+    for (let i = 0; i < rest.length; i += 1) {
+        const a = rest[i];
+        if (a === "--help" || a === "-h")
+            throw new Error("help");
+        if (a === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (withYes && (a === "-y" || a === "--yes")) {
+            yes = true;
+            continue;
+        }
+        if ((a === "-bd" || a === "--biz-domain") && rest[i + 1]) {
+            businessDomain = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--branch" && rest[i + 1]) {
+            branch = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--strict-mode" && rest[i + 1]) {
+            strictMode = rest[i + 1] === "true" || rest[i + 1] === "1";
+            i += 1;
+            continue;
+        }
+        if (a === "--import-mode" && rest[i + 1]) {
+            const m = rest[i + 1];
+            if (m !== "normal" && m !== "ignore" && m !== "overwrite") {
+                throw new Error("--import-mode must be normal|ignore|overwrite");
+            }
+            importMode = m;
+            i += 1;
+            continue;
+        }
+        if (a === "--fill-null") {
+            fillNull = true;
+            continue;
+        }
+        out.push(a);
+    }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    return { filtered: out, pretty, businessDomain, branch, strictMode, importMode, fillNull, yes };
+}
+export async function runKnMetricCommand(args) {
+    const [action, ...rest] = args;
+    if (!action || action === "--help" || action === "-h") {
+        console.log(METRIC_HELP);
+        return 0;
+    }
+    try {
+        const token = await ensureValidToken();
+        const b = { baseUrl: token.baseUrl, accessToken: token.accessToken };
+        if (action === "list") {
+            const p = parseListArgs(rest);
+            const out = await listMetrics({
+                ...b,
+                knId: p.knId,
+                businessDomain: p.businessDomain,
+                limit: p.limit,
+                branch: p.branch,
+                namePattern: p.namePattern,
+                sort: p.sort,
+                direction: p.direction,
+                offset: p.offset,
+                tag: p.tag,
+                groupId: p.groupId,
+            });
+            console.log(formatCallOutput(out, p.pretty));
+            return 0;
+        }
+        if (action === "get") {
+            const o = parseCommonKnFlags(rest, false);
+            const [knId, metricIdArg] = o.filtered;
+            if (!knId || !metricIdArg) {
+                console.error("Usage: kweaver bkn metric get <kn-id> <metric-id(s)> [options]");
+                return 1;
+            }
+            const ids = parseCommaSeparatedIds(metricIdArg);
+            if (ids.length === 0) {
+                console.error("metric-id(s): need at least one id");
+                return 1;
+            }
+            const out = ids.length === 1
+                ? await getMetric({ ...b, knId, businessDomain: o.businessDomain, metricId: ids[0], branch: o.branch })
+                : await getMetrics({ ...b, knId, businessDomain: o.businessDomain, metricIds: ids.join(","), branch: o.branch });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "create") {
+            const o = parseCommonKnFlags(rest, false);
+            const [knId, bodyJson] = o.filtered;
+            if (!knId || !bodyJson) {
+                console.error("Usage: kweaver bkn metric create <kn-id> '<json>' [options]");
+                return 1;
+            }
+            const out = await createMetrics({
+                ...b,
+                knId,
+                businessDomain: o.businessDomain,
+                body: bodyJson,
+                branch: o.branch,
+                strictMode: o.strictMode,
+            });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "search") {
+            let limit;
+            let searchAfter;
+            const r = [];
+            for (let i = 0; i < rest.length; i += 1) {
+                const a = rest[i];
+                if (a === "--limit" && rest[i + 1]) {
+                    limit = parseInt(rest[i + 1], 10);
+                    if (Number.isNaN(limit) || limit < 1)
+                        throw new Error("Invalid --limit");
+                    i += 1;
+                    continue;
+                }
+                if (a === "--search-after" && rest[i + 1]) {
+                    searchAfter = parseSearchAfterArray(rest[i + 1]);
+                    i += 1;
+                    continue;
+                }
+                r.push(a);
+            }
+            const o = parseCommonKnFlags(r, false);
+            const [knId, bodyText] = o.filtered;
+            if (!knId || !bodyText) {
+                console.error("Usage: kweaver bkn metric search <kn-id> '<json>' [options]");
+                return 1;
+            }
+            const obj = parseJsonObject(bodyText, "search body must be a JSON object.");
+            if (limit !== undefined)
+                obj.limit = limit;
+            if (searchAfter !== undefined)
+                obj.search_after = searchAfter;
+            if (typeof obj.limit !== "number" || !Number.isFinite(obj.limit)) {
+                obj.limit = 50;
+            }
+            const out = await searchMetrics({
+                ...b,
+                knId,
+                businessDomain: o.businessDomain,
+                body: JSON.stringify(obj),
+                branch: o.branch,
+                strictMode: o.strictMode,
+            });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "validate") {
+            const o = parseCommonKnFlags(rest, false);
+            const [knId, bodyJson] = o.filtered;
+            if (!knId || !bodyJson) {
+                console.error("Usage: kweaver bkn metric validate <kn-id> '<json>' [options]");
+                return 1;
+            }
+            const out = await validateMetrics({
+                ...b,
+                knId,
+                businessDomain: o.businessDomain,
+                body: bodyJson,
+                branch: o.branch,
+                strictMode: o.strictMode,
+                importMode: o.importMode,
+            });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "update") {
+            const o = parseCommonKnFlags(rest, false);
+            const [knId, metricId, bodyJson] = o.filtered;
+            if (!knId || !metricId || !bodyJson) {
+                console.error("Usage: kweaver bkn metric update <kn-id> <metric-id> '<json>' [options]");
+                return 1;
+            }
+            const out = await updateMetric({
+                ...b,
+                knId,
+                businessDomain: o.businessDomain,
+                metricId,
+                body: bodyJson,
+                branch: o.branch,
+                strictMode: o.strictMode,
+            });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "delete") {
+            const o = parseCommonKnFlags(rest, true);
+            const [knId, metricIdArg] = o.filtered;
+            if (!knId || !metricIdArg) {
+                console.error("Usage: kweaver bkn metric delete <kn-id> <metric-id(s)> [-y]");
+                return 1;
+            }
+            const ids = parseCommaSeparatedIds(metricIdArg);
+            if (ids.length === 0) {
+                console.error("metric-id(s): need at least one id");
+                return 1;
+            }
+            if (!o.yes) {
+                const label = ids.length === 1 ? ids[0] : ids.join(",");
+                const ok = await confirmYes(`Delete metric(s) ${label}?`);
+                if (!ok) {
+                    console.log("Cancelled.");
+                    return 0;
+                }
+            }
+            const out = ids.length === 1
+                ? await deleteMetric({ ...b, knId, businessDomain: o.businessDomain, metricId: ids[0], branch: o.branch })
+                : await deleteMetrics({ ...b, knId, businessDomain: o.businessDomain, metricIds: ids.join(","), branch: o.branch });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "query") {
+            const o = parseCommonKnFlags(rest, false);
+            const { fillNull, branch, filtered, pretty, businessDomain } = o;
+            const [knId, metricId, bodyText = "{}"] = filtered;
+            if (!knId || !metricId) {
+                console.error("Usage: kweaver bkn metric query <kn-id> <metric-id> ['<json>'] [--branch] [--fill-null]");
+                return 1;
+            }
+            const body = parseJsonObject(bodyText, "metric query body must be a JSON object.");
+            if (typeof body.limit !== "number" || !Number.isFinite(body.limit)) {
+                body.limit = 50;
+            }
+            const out = await metricQueryData({
+                ...b,
+                knId,
+                businessDomain,
+                metricId,
+                body: JSON.stringify(body),
+                branch,
+                fillNull,
+            });
+            console.log(formatCallOutput(out, pretty));
+            return 0;
+        }
+        if (action === "dry-run") {
+            const o = parseCommonKnFlags(rest, false);
+            const { fillNull, branch, filtered, pretty, businessDomain } = o;
+            const [knId, bodyText] = filtered;
+            if (!knId || !bodyText) {
+                console.error("Usage: kweaver bkn metric dry-run <kn-id> '<json>' [--branch] [--fill-null]");
+                return 1;
+            }
+            parseJsonObject(bodyText, "dry-run body must be a JSON object.");
+            const out = await metricDryRun({
+                ...b,
+                knId,
+                businessDomain,
+                body: bodyText,
+                branch,
+                fillNull,
+            });
+            console.log(formatCallOutput(out, pretty));
+            return 0;
+        }
+        console.error(`Unknown bkn metric action: ${action}. Use --help.`);
+        return 1;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(METRIC_HELP);
+            return 0;
+        }
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}

package/dist/commands/bkn-ops.d.ts

@@ -32,6 +32,7 @@ export declare function parseKnCreateFromDsArgs(args: string[]): {
     dsId: string;
     name: string;
     tables: string[];
+    pkMap: Record<string, string>;
     build: boolean;
     timeout: number;
     businessDomain: string;
@@ -51,8 +52,8 @@ export declare function parseKnCreateFromCsvArgs(args: string[]): {
     tablePrefix: string;
     batchSize: number;
     tables: string[];
+    pkMap: Record<string, string>;
     build: boolean;
-    recreate: boolean;
     timeout: number;
     businessDomain: string;
     noRollback: boolean;

package/dist/commands/bkn-ops.js

@@ -5,7 +5,7 @@ import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, va
 import { prepareBknDirectoryForImport, stripBknEncodingCliArgs, } from "../utils/bkn-encoding.js";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
 import { createKnowledgeNetwork, createObjectTypes, deleteKnowledgeNetwork, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
-import { listTablesWithColumns, scanMetadata, getDatasource } from "../api/datasources.js";
+import { listTablesWithColumns, scanDatasourceMetadata } from "../api/datasources.js";
 import { createDataView, findDataView } from "../api/dataviews.js";
 import { resolveFiles } from "./ds.js";
 import { buildTableName } from "./import-csv.js";
@@ -13,7 +13,7 @@ import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createA
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
-import { pollWithBackoff, detectPrimaryKey, detectDisplayKey, confirmYes, } from "./bkn-utils.js";
+import { pollWithBackoff, detectDisplayKey, formatPkDetectionError, parsePkMap, resolvePrimaryKey, confirmYes, } from "./bkn-utils.js";
 // ── BKN object name validation ──────────────────────────────────────────────
 // Mirrors bkn-backend OBJECT_NAME_MAX_LENGTH (interfaces/common.go:28) and
 // validateObjectName (driveradapters/validate.go:85). 40 utf-8 codepoints,
@@ -480,6 +480,8 @@ Create a knowledge network from a datasource (dataviews + object types + optiona
 Options:
   --name <s>       Knowledge network name (required)
   --tables <a,b>   Comma-separated table names (default: all)
+  --pk-map <s>     Explicit primary keys: <table>:<field>[,<table>:<field>...]
+                   Required when auto-detection fails (no unique column in sample)
   --build (default)  Build after creation
   --no-build       Skip build after creation
   --timeout <n>    Build timeout in seconds (default: 300)
@@ -490,6 +492,7 @@ export function parseKnCreateFromDsArgs(args) {
     let dsId = "";
     let name = "";
     let tablesStr = "";
+    let pkMapStr = "";
     let build = true;
     let timeout = 300;
     let businessDomain = "";
@@ -507,6 +510,10 @@ export function parseKnCreateFromDsArgs(args) {
             tablesStr = args[++i];
             continue;
         }
+        if (arg === "--pk-map" && args[i + 1]) {
+            pkMapStr = args[++i];
+            continue;
+        }
         if (arg === "--build") {
             build = true;
             continue;
@@ -541,9 +548,10 @@ export function parseKnCreateFromDsArgs(args) {
     if (!dsId || !name) {
         throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
     }
+    const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, name, tables, build, timeout, businessDomain, pretty, noRollback };
+    return { dsId, name, tables, pkMap, build, timeout, businessDomain, pretty, noRollback };
 }
 /** Sanitize a table name into a BKN-safe ID (alphanumeric + underscore). */
 function sanitizeBknId(name) {
@@ -587,6 +595,7 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         const tableRetryDelayMs = 4000;
         let allTables = [];
         let targetTables = [];
+        let scanAttempted = false;
         for (let attempt = 1; attempt <= maxTableListAttempts; attempt += 1) {
             const tablesBody = await listTablesWithColumns({ ...base, id: options.dsId });
             allTables = JSON.parse(tablesBody);
@@ -596,8 +605,24 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
             if (targetTables.length > 0)
                 break;
             if (attempt < maxTableListAttempts) {
-                console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); retrying in ${tableRetryDelayMs / 1000}s...`);
-                await new Promise((r) => setTimeout(r, tableRetryDelayMs));
+                // First miss: the catalog often hasn't picked up tables created
+                // out-of-band (e.g. ds import-csv from an older SDK that didn't
+                // self-scan). Trigger a scan once before falling back to plain
+                // sleep-retries.
+                if (!scanAttempted) {
+                    scanAttempted = true;
+                    console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); scanning datasource metadata before retry...`);
+                    try {
+                        await scanDatasourceMetadata({ ...base, id: options.dsId });
+                    }
+                    catch (err) {
+                        console.error(`Scan warning (continuing): ${formatHttpError(err)}`);
+                    }
+                }
+                else {
+                    console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); retrying in ${tableRetryDelayMs / 1000}s...`);
+                    await new Promise((r) => setTimeout(r, tableRetryDelayMs));
+                }
             }
         }
         if (targetTables.length === 0) {
@@ -608,6 +633,37 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         // Backend rejects the whole batch on first violation (validate.go:90),
         // so retroactive rollback is wasted work if we can fail fast here.
         assertValidBknObjectNames(targetTables.map((t) => t.name), "Object type names derived from table names");
+        // Pre-flight: resolve PK for every table BEFORE any side effect.
+        // Auto-detection silently picking the wrong column was the cause of
+        // issue #97 (KN built with ~5 indexed docs out of 2036 source rows).
+        // Resolve order: --pk-map override → cardinality-based detection → fail-fast.
+        const tablePks = {};
+        const unknownPkMapTables = Object.keys(options.pkMap).filter((name) => !targetTables.some((t) => t.name === name));
+        if (unknownPkMapTables.length > 0) {
+            throw new Error(`--pk-map references unknown table(s): ${unknownPkMapTables.join(", ")}`);
+        }
+        for (const t of targetTables) {
+            const override = options.pkMap[t.name];
+            if (override && !t.columns.some((c) => c.name === override)) {
+                throw new Error(`--pk-map specifies '${override}' for table '${t.name}', but no such column. ` +
+                    `Columns: ${t.columns.map((c) => c.name).join(", ")}`);
+            }
+            const resolution = resolvePrimaryKey(t, sampleRows?.[t.name], override);
+            if (resolution.pk) {
+                tablePks[t.name] = resolution.pk;
+                continue;
+            }
+            if (resolution.source === "ambiguous") {
+                const cols = (resolution.ambiguous ?? []).join(", ");
+                throw new Error(`Table '${t.name}' has a composite PRIMARY KEY (${cols}). ` +
+                    `BKN object types take a single primary key — pick one with --pk-map ${t.name}:<column>.`);
+            }
+            throw new Error(formatPkDetectionError(t.name, {
+                pk: null,
+                candidates: resolution.candidates ?? [],
+                sampleSize: resolution.sampleSize ?? 0,
+            }));
+        }
         // Phase 1: Create DataViews for each table. findDataView is idempotent;
         // not tracked for rollback so a retry can reuse what's already there.
         console.error(`Creating data views for ${targetTables.length} table(s) ...`);
@@ -653,7 +709,7 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
             // (object_type_service.go:213-355) — all-or-nothing.
             console.error(`Creating ${targetTables.length} object type(s) ...`);
             const entries = targetTables.map((t) => {
-                const pk = detectPrimaryKey(t, sampleRows?.[t.name]);
+                const pk = tablePks[t.name];
                 const dk = detectDisplayKey(t, pk);
                 return {
                     branch: "main",
@@ -759,7 +815,7 @@ Options:
   --tables <a,b>       Tables to include in KN (default: all imported)
   --build (default)    Build after creation
   --no-build           Skip build
-  --recreate           Use "insert" mode on first batch (only effective for new tables)
+  --pk-map <s>         Explicit primary keys: <table>:<field>[,<table>:<field>...]
   --timeout <n>        Build timeout in seconds (default: 300)
   --no-rollback        Keep partially-created KN on failure (debug; default: rollback)
   -bd, --biz-domain    Business domain (default: bd_public)`;
@@ -770,8 +826,8 @@ export function parseKnCreateFromCsvArgs(args) {
     let tablePrefix = "";
     let batchSize = 500;
     let tablesStr = "";
+    let pkMapStr = "";
     let build = true;
-    let recreate = false;
     let timeout = 300;
     let businessDomain = "";
     let noRollback = false;
@@ -809,8 +865,8 @@ export function parseKnCreateFromCsvArgs(args) {
             build = false;
             continue;
         }
-        if (arg === "--recreate") {
-            recreate = true;
+        if (arg === "--pk-map" && args[i + 1]) {
+            pkMapStr = args[++i];
             continue;
         }
         if (arg === "--no-rollback") {
@@ -835,9 +891,10 @@ export function parseKnCreateFromCsvArgs(args) {
     if (!dsId || !files || !name) {
         throw new Error("Usage: kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]");
     }
+    const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, files, name, tablePrefix, batchSize, tables, build, recreate, timeout, businessDomain, noRollback };
+    return { dsId, files, name, tablePrefix, batchSize, tables, pkMap, build, timeout, businessDomain, noRollback };
 }
 export async function runKnCreateFromCsvCommand(args) {
     let options;
@@ -874,35 +931,15 @@ export async function runKnCreateFromCsvCommand(args) {
         "--table-prefix", options.tablePrefix,
         "--batch-size", String(options.batchSize),
         "-bd", options.businessDomain,
-        ...(options.recreate ? ["--recreate"] : []),
     ];
     const importResult = await runDsImportCsv(importArgs);
     if (importResult.code !== 0) {
         console.error("CSV import failed — aborting KN creation");
         return importResult.code;
     }
-    // Phase 1.5: Scan datasource metadata so platform discovers newly imported tables
-    console.error("Scanning datasource metadata ...");
-    try {
-        const token = await ensureValidToken();
-        const dsBody = await getDatasource({
-            baseUrl: token.baseUrl,
-            accessToken: token.accessToken,
-            id: options.dsId,
-            businessDomain: options.businessDomain,
-        });
-        const dsParsed = JSON.parse(dsBody);
-        await scanMetadata({
-            baseUrl: token.baseUrl,
-            accessToken: token.accessToken,
-            id: options.dsId,
-            dsType: dsParsed.type ?? "mysql",
-            businessDomain: options.businessDomain,
-        });
-    }
-    catch (err) {
-        console.error(`Scan warning (continuing): ${String(err)}`);
-    }
+    // (Phase 1.5 metadata scan removed — runDsImportCsv now self-scans on
+    // success, and runKnCreateFromDsCommand's table-discovery retry triggers
+    // a scan if the catalog still lags. Two layers of fallback are enough.)
     // Phase 2: Create KN from datasource
     console.error("Phase 2: Creating knowledge network ...");
     const tableNames = options.tables.length > 0 ? options.tables : importResult.tables;
@@ -910,6 +947,7 @@ export async function runKnCreateFromCsvCommand(args) {
         console.error("No tables available for KN creation — aborting");
         return 1;
     }
+    const pkMapEntries = Object.entries(options.pkMap);
     const knArgs = [
         options.dsId,
         "--name", options.name,
@@ -917,6 +955,9 @@ export async function runKnCreateFromCsvCommand(args) {
         options.build ? "--build" : "--no-build",
         "--timeout", String(options.timeout),
         "-bd", options.businessDomain,
+        ...(pkMapEntries.length > 0
+            ? ["--pk-map", pkMapEntries.map(([t, f]) => `${t}:${f}`).join(",")]
+            : []),
         ...(options.noRollback ? ["--no-rollback"] : []),
     ];
     return runKnCreateFromDsCommand(knArgs, importResult.sampleRows);