@ultipa-graph/ultipa-driver 6.0.9 → 6.0.11

package/dist/client.d.ts

@@ -6,7 +6,7 @@ import { GqldbConfig } from './config';
 import { Response, InsertNodesResult, InsertEdgesResult, DeleteResult, ExportNodesResult, ExportEdgesResult, ExportConfig, ExportChunk } from './response';
 import { Session } from './session';
 import { Transaction } from './transaction';
-import { GraphInfo, GraphType, HealthStatus, CacheStats, CacheType, Statistics, CompactResult, ComputeTopologyResult, SystemMetrics, NodeData, EdgeData, BulkCreateNodesOptions, BulkCreateEdgesOptions, BulkImportOptions, BulkImportSession, CheckpointResult, EndBulkImportResult, AbortBulkImportResult, BulkImportStatus, TransactionInfo, DBType, InsertType, LabelInfo, NodeTypeInfo, EdgeTypeInfo, ConvPropertyDef, IndexProperty, IndexInfo, FulltextInfo, TaskInfo, ProcessInfo, GraphStats, AlgoInfo } from './types';
+import { GraphInfo, GraphType, HealthStatus, CacheStats, CacheType, Statistics, CompactResult, ComputeTopologyResult, SystemMetrics, NodeData, EdgeData, BulkCreateNodesOptions, BulkCreateEdgesOptions, BulkImportOptions, BulkImportSession, CheckpointResult, EndBulkImportResult, AbortBulkImportResult, BulkImportStatus, TransactionInfo, DBType, InsertType, LabelInfo, NodeTypeInfo, EdgeTypeInfo, ConvPropertyDef, IndexProperty, IndexInfo, FulltextInfo, TaskInfo, ProcessInfo, GraphStats, AlgoInfo, AiReadResult } from './types';
 /** Configuration for a query */
 export interface QueryConfig {
     graphName?: string;
@@ -17,6 +17,14 @@ export interface QueryConfig {
     /** Max paths to return from path queries (0 = unlimited) */
     maxPathResults?: number;
 }
+/**
+ * Configuration for insertNodes / insertEdges convenience methods.
+ * Extends QueryConfig with insert-specific options.
+ */
+export interface InsertConfig extends QueryConfig {
+    /** Insert mode. Defaults to InsertType.Normal when omitted. */
+    insertType?: InsertType;
+}
 /** Configuration for insert nodes */
 export interface InsertNodesConfig {
     options?: BulkCreateNodesOptions;
@@ -210,10 +218,14 @@ export declare class GqldbClient {
     private static quoteLabels;
     /** Join names with ", " without backtick wrapping */
     private static joinNames;
-    /** Create a new open (schema-less) graph */
-    createOpenGraph(name: string): Promise<Response>;
+    /** Create a new open (schema-less) graph
+     *
+     * v6 GQL: `CREATE GRAPH g` -> OPEN; `CREATE GRAPH g {}` -> CLOSED. The
+     * brace-less form is required to actually get an OPEN graph.
+     */
+    createOpenGraph(name: string, config?: QueryConfig): Promise<Response>;
     /** Create a new closed (schema-enforced) graph with node and edge label definitions */
-    createClosedGraph(name: string): Promise<Response>;
+    createClosedGraph(name: string, config?: QueryConfig): Promise<Response>;
     /**
      * Create a graph if it does not already exist.
      * Returns true if the graph was created, false if it already existed.
@@ -222,137 +234,173 @@ export declare class GqldbClient {
     /** Check whether a graph with the given name exists */
     hasGraph(name: string): Promise<boolean>;
     /** Rename a graph */
-    alterGraph(graphName: string, newName: string): Promise<Response>;
+    alterGraph(graphName: string, newName: string, config?: QueryConfig): Promise<Response>;
     /** Remove all data from a graph while keeping its structure */
-    truncate(graphName: string): Promise<Response>;
+    truncate(graphName: string, config?: QueryConfig): Promise<Response>;
     /** Return all labels (node and edge) in the current graph */
-    showLabels(): Promise<LabelInfo[]>;
+    showLabels(config?: QueryConfig): Promise<LabelInfo[]>;
     /** Return all node labels in the current graph */
-    showNodeLabels(): Promise<LabelInfo[]>;
+    showNodeLabels(config?: QueryConfig): Promise<LabelInfo[]>;
     /** Return all edge labels in the current graph */
-    showEdgeLabels(): Promise<LabelInfo[]>;
+    showEdgeLabels(config?: QueryConfig): Promise<LabelInfo[]>;
     /** Return all node types with their properties */
-    showNodeTypes(): Promise<NodeTypeInfo[]>;
+    showNodeTypes(config?: QueryConfig): Promise<NodeTypeInfo[]>;
     /** Return all edge types with their properties */
-    showEdgeTypes(): Promise<EdgeTypeInfo[]>;
-    /** Return a specific label by name from the current graph, or null if not found */
-    getLabel(name: string): Promise<LabelInfo | null>;
+    showEdgeTypes(config?: QueryConfig): Promise<EdgeTypeInfo[]>;
+    /**
+     * Return a specific label by name from the current graph, or null if not found.
+     * Matches entries where `name` is one of the .labels (supports multi-label groups).
+     */
+    getLabel(name: string, config?: QueryConfig): Promise<LabelInfo | null>;
     /** Return a specific node type by name, or null if not found */
-    getNodeLabel(name: string): Promise<NodeTypeInfo | null>;
+    getNodeLabel(name: string, config?: QueryConfig): Promise<NodeTypeInfo | null>;
     /** Return a specific edge type by name, or null if not found */
-    getEdgeLabel(name: string): Promise<EdgeTypeInfo | null>;
+    getEdgeLabel(name: string, config?: QueryConfig): Promise<EdgeTypeInfo | null>;
     /** Create a node label in the current graph (closed graph) */
-    createNodeLabel(name: string, props?: ConvPropertyDef[]): Promise<Response>;
+    createNodeLabel(name: string, props?: ConvPropertyDef[], config?: QueryConfig): Promise<Response>;
     /** Create an edge label in the current graph (closed graph) */
-    createEdgeLabel(name: string, props?: ConvPropertyDef[]): Promise<Response>;
+    createEdgeLabel(name: string, props?: ConvPropertyDef[], config?: QueryConfig): Promise<Response>;
     /** Drop a node label from the current graph (closed graph) */
-    dropNodeLabel(name: string): Promise<Response>;
+    dropNodeLabel(name: string, config?: QueryConfig): Promise<Response>;
     /** Drop one or more edge labels from the current graph (closed graph) */
-    dropEdgeLabel(...names: string[]): Promise<Response>;
+    dropEdgeLabel(...namesOrConfig: Array<string | QueryConfig | undefined>): Promise<Response>;
     /**
      * Create a label if it does not already exist.
      * Returns true if created, false if it already existed.
      */
-    createLabelIfNotExist(nodeOrEdge: DBType, name: string, props?: ConvPropertyDef[]): Promise<boolean>;
+    createLabelIfNotExist(nodeOrEdge: DBType, name: string, props?: ConvPropertyDef[], config?: QueryConfig): Promise<boolean>;
     /** Rename a node label */
-    alterNodeLabel(oldName: string, newName: string): Promise<Response>;
+    alterNodeLabel(oldName: string, newName: string, config?: QueryConfig): Promise<Response>;
     /** Rename an edge label */
-    alterEdgeLabel(oldName: string, newName: string): Promise<Response>;
+    alterEdgeLabel(oldName: string, newName: string, config?: QueryConfig): Promise<Response>;
     /** Return all available algorithms */
-    showAlgos(): Promise<AlgoInfo[]>;
+    showAlgos(config?: QueryConfig): Promise<AlgoInfo[]>;
     /** Return properties for a label (node or edge) in the current graph */
-    showProperty(nodeOrEdge: DBType, labelName: string): Promise<ConvPropertyDef[]>;
+    showProperty(nodeOrEdge: DBType, labelName: string, config?: QueryConfig): Promise<ConvPropertyDef[]>;
     /** Return properties for a node label */
-    showNodeProperty(labelName: string): Promise<ConvPropertyDef[]>;
+    showNodeProperty(labelName: string, config?: QueryConfig): Promise<ConvPropertyDef[]>;
     /** Return properties for an edge label */
-    showEdgeProperty(labelName: string): Promise<ConvPropertyDef[]>;
+    showEdgeProperty(labelName: string, config?: QueryConfig): Promise<ConvPropertyDef[]>;
     /** Return a specific property definition for a label, or null if not found */
-    getProperty(nodeOrEdge: DBType, labelName: string, propName: string): Promise<ConvPropertyDef | null>;
+    getProperty(nodeOrEdge: DBType, labelName: string, propName: string, config?: QueryConfig): Promise<ConvPropertyDef | null>;
     /** Return a specific property definition for a node label, or null if not found */
-    getNodeProperty(labelName: string, propName: string): Promise<ConvPropertyDef | null>;
+    getNodeProperty(labelName: string, propName: string, config?: QueryConfig): Promise<ConvPropertyDef | null>;
     /** Return a specific property definition for an edge label, or null if not found */
-    getEdgeProperty(labelName: string, propName: string): Promise<ConvPropertyDef | null>;
+    getEdgeProperty(labelName: string, propName: string, config?: QueryConfig): Promise<ConvPropertyDef | null>;
     /** Add properties to a label (node or edge) */
-    createProperty(nodeOrEdge: DBType, labelName: string, props: ConvPropertyDef[]): Promise<Response>;
+    createProperty(nodeOrEdge: DBType, labelName: string, props: ConvPropertyDef[], config?: QueryConfig): Promise<Response>;
     /** Add properties to a node label */
-    createNodeProperty(labelName: string, props: ConvPropertyDef[]): Promise<Response>;
+    createNodeProperty(labelName: string, props: ConvPropertyDef[], config?: QueryConfig): Promise<Response>;
     /** Add properties to an edge label */
-    createEdgeProperty(labelName: string, props: ConvPropertyDef[]): Promise<Response>;
+    createEdgeProperty(labelName: string, props: ConvPropertyDef[], config?: QueryConfig): Promise<Response>;
     /** Drop properties from a label (node or edge) */
-    dropProperty(nodeOrEdge: DBType, labelName: string, ...propNames: string[]): Promise<Response>;
+    dropProperty(nodeOrEdge: DBType, labelName: string, ...propNamesOrConfig: Array<string | QueryConfig | undefined>): Promise<Response>;
     /** Drop properties from a node label */
-    dropNodeProperty(labelName: string, ...propNames: string[]): Promise<Response>;
+    dropNodeProperty(labelName: string, ...propNamesOrConfig: Array<string | QueryConfig | undefined>): Promise<Response>;
     /** Drop properties from an edge label */
-    dropEdgeProperty(labelName: string, ...propNames: string[]): Promise<Response>;
+    dropEdgeProperty(labelName: string, ...propNamesOrConfig: Array<string | QueryConfig | undefined>): Promise<Response>;
     /**
      * Create properties on a label if they do not already exist.
      * Returns true if any properties were created, false if all already existed.
      */
-    createPropertyIfNotExist(nodeOrEdge: DBType, labelName: string, props: ConvPropertyDef[]): Promise<boolean>;
+    createPropertyIfNotExist(nodeOrEdge: DBType, labelName: string, props: ConvPropertyDef[], config?: QueryConfig): Promise<boolean>;
     /** Create a NOT NULL constraint on a property */
-    createNotNullConstraint(nodeOrEdge: DBType, labelName: string, propName: string): Promise<Response>;
+    createNotNullConstraint(nodeOrEdge: DBType, labelName: string, propName: string, config?: QueryConfig): Promise<Response>;
     /** Create a UNIQUE constraint on one or more properties */
-    createUniqueConstraint(nodeOrEdge: DBType, labelName: string, ...propNames: string[]): Promise<Response>;
+    createUniqueConstraint(nodeOrEdge: DBType, labelName: string, ...propNamesOrConfig: Array<string | QueryConfig | undefined>): Promise<Response>;
     /** Remove a NOT NULL constraint from a property */
-    dropNotNullConstraint(nodeOrEdge: DBType, labelName: string, propName: string): Promise<Response>;
+    dropNotNullConstraint(nodeOrEdge: DBType, labelName: string, propName: string, config?: QueryConfig): Promise<Response>;
     /** Remove a UNIQUE constraint from one or more properties */
-    dropUniqueConstraint(nodeOrEdge: DBType, labelName: string, ...propNames: string[]): Promise<Response>;
+    dropUniqueConstraint(nodeOrEdge: DBType, labelName: string, ...propNamesOrConfig: Array<string | QueryConfig | undefined>): Promise<Response>;
     /** Return all indexes in the current graph */
-    showIndex(): Promise<IndexInfo[]>;
+    showIndex(config?: QueryConfig): Promise<IndexInfo[]>;
     /** Return all node indexes in the current graph */
-    showNodeIndex(): Promise<IndexInfo[]>;
+    showNodeIndex(config?: QueryConfig): Promise<IndexInfo[]>;
     /** Return all edge indexes in the current graph */
-    showEdgeIndex(): Promise<IndexInfo[]>;
+    showEdgeIndex(config?: QueryConfig): Promise<IndexInfo[]>;
     /** Create an index on a node label */
-    createNodeIndex(indexName: string, labelName: string, props: IndexProperty[]): Promise<Response>;
+    createNodeIndex(indexName: string, labelName: string, props: IndexProperty[], config?: QueryConfig): Promise<Response>;
     /** Create an index on an edge label */
-    createEdgeIndex(indexName: string, labelName: string, props: IndexProperty[]): Promise<Response>;
+    createEdgeIndex(indexName: string, labelName: string, props: IndexProperty[], config?: QueryConfig): Promise<Response>;
     /** Drop a node index by name */
-    dropNodeIndex(indexName: string): Promise<Response>;
+    dropNodeIndex(indexName: string, config?: QueryConfig): Promise<Response>;
     /** Drop an edge index by name */
-    dropEdgeIndex(indexName: string): Promise<Response>;
+    dropEdgeIndex(indexName: string, config?: QueryConfig): Promise<Response>;
     /** Return all fulltext indexes in the current graph */
-    showFulltext(): Promise<FulltextInfo[]>;
+    showFulltext(config?: QueryConfig): Promise<FulltextInfo[]>;
     /** Return all node fulltext indexes */
-    showNodeFulltext(): Promise<FulltextInfo[]>;
+    showNodeFulltext(config?: QueryConfig): Promise<FulltextInfo[]>;
     /** Return all edge fulltext indexes */
-    showEdgeFulltext(): Promise<FulltextInfo[]>;
+    showEdgeFulltext(config?: QueryConfig): Promise<FulltextInfo[]>;
     /** Create a fulltext index on a node label */
-    createNodeFulltext(indexName: string, labelName: string, props: string[]): Promise<Response>;
+    createNodeFulltext(indexName: string, labelName: string, props: string[], config?: QueryConfig): Promise<Response>;
     /** Create a fulltext index on an edge label */
-    createEdgeFulltext(indexName: string, labelName: string, props: string[]): Promise<Response>;
+    createEdgeFulltext(indexName: string, labelName: string, props: string[], config?: QueryConfig): Promise<Response>;
     /** Drop a node fulltext index by name */
-    dropNodeFulltext(indexName: string): Promise<Response>;
+    dropNodeFulltext(indexName: string, config?: QueryConfig): Promise<Response>;
     /** Drop an edge fulltext index by name */
-    dropEdgeFulltext(indexName: string): Promise<Response>;
+    dropEdgeFulltext(indexName: string, config?: QueryConfig): Promise<Response>;
     /** Return all tasks in the current graph */
-    showTasks(): Promise<TaskInfo[]>;
+    showTasks(config?: QueryConfig): Promise<TaskInfo[]>;
     /** Delete a task by ID */
-    deleteTask(taskId: string): Promise<Response>;
+    deleteTask(taskId: string, config?: QueryConfig): Promise<Response>;
     /** Stop a running task by ID */
-    stopTask(taskId: string): Promise<Response>;
-    /** Insert nodes using GQL INSERT syntax */
+    stopTask(taskId: string, config?: QueryConfig): Promise<Response>;
     /**
      * Insert nodes using GQL INSERT syntax with RETURN clause.
      * GQL: INSERT (n0:Label {p1: v1}), (n1:Label {p2: v2}) RETURN n0, n1
+     * When config.insertType is InsertType.Overwrite, uses INSERT OVERWRITE syntax.
      * If NodeData.id is set (non-empty), includes it as _id property in the GQL.
      * Returns the raw Response containing the inserted nodes in columns n0, n1, etc.
+     *
+     * @param nodes Nodes to insert.
+     * @param config Optional InsertConfig. Supports per-call graphName and insertType.
      */
-    insertNodes(nodes: NodeData[], insertType?: InsertType): Promise<Response>;
+    insertNodes(nodes: NodeData[], config?: InsertConfig): Promise<Response>;
     /**
      * Insert edges using GQL INSERT syntax with RETURN clause.
      * Each edge is inserted individually using MATCH + INSERT to resolve node IDs.
      * GQL: MATCH (src WHERE id(src) = 'from'), (dst WHERE id(dst) = 'to')
      *      INSERT (src)-[e0:Label {p1: v1}]->(dst) RETURN e0
+     * When config.insertType is InsertType.Overwrite, uses INSERT OVERWRITE syntax.
      * Returns a merged Response containing all inserted edges in columns e0, e1, etc.
+     *
+     * @param edges Edges to insert.
+     * @param config Optional InsertConfig. Supports per-call graphName and insertType.
      */
-    insertEdges(edges: EdgeData[], insertType?: InsertType): Promise<Response>;
+    insertEdges(edges: EdgeData[], config?: InsertConfig): Promise<Response>;
     /** Return currently running processes (queries) */
-    top(): Promise<ProcessInfo[]>;
+    top(config?: QueryConfig): Promise<ProcessInfo[]>;
     /** Terminate a running query by its query ID */
-    kill(queryId: string): Promise<Response>;
+    kill(queryId: string, config?: QueryConfig): Promise<Response>;
     /** Return statistics for the current graph using db.stats() */
-    stats(): Promise<GraphStats>;
+    stats(config?: QueryConfig): Promise<GraphStats>;
     /** Send a ping to the server and return the latency in nanoseconds */
     test(): Promise<number>;
+    /** YIELD columns emitted by CALL ai.read / ai.gql (kept in sync with server). */
+    private static readonly AI_YIELD_COLS;
+    /**
+     * Ask the AI to generate a GQL statement and auto-execute it.
+     *
+     * Wraps `CALL ai.read("<prompt>") YIELD ...`, streams stage rows from the
+     * server, and re-runs the synthesized GQL so `AiReadResult.data` holds the
+     * real query {@link Response} (rows / columns) — matching what Manager UI
+     * displays.
+     *
+     * Only transport-level errors reject the Promise. AI-side errors set
+     * `success=false` and populate `error`, with `data=null`.
+     */
+    aiRead(prompt: string, config?: QueryConfig): Promise<AiReadResult>;
+    /**
+     * Ask the AI to generate a GQL statement *without* executing it.
+     *
+     * The generated GQL is exposed via `AiReadResult.generatedGql` so the
+     * caller can review / edit it before running it manually via `client.gql()`.
+     * `AiReadResult.data` is always null for `aiGql`.
+     */
+    aiGql(prompt: string, config?: QueryConfig): Promise<AiReadResult>;
+    /** Escape a prompt so it can be safely embedded in a double-quoted GQL string. */
+    private static escapeAiPrompt;
+    /** Parse a CALL ai.read / ai.gql YIELD response into an AiReadResult. */
+    private parseAiResult;
 }