@ultipa-graph/ultipa-driver/dist/response.d.ts

NodeJS SDK for Ultipa GQL

/**
 * Response handling for GQLDB Node.js driver.
 */
import { PropertyType, Schema, Table, Attr } from './types';
/**
 * Represents a single row in the query result.
 *
 * Positional access via `row.get(i)` is always available. Name-based
 * access via `row.getByName(name)` / `row.has(name)` requires the parent
 * Response to have populated {@link Row.columnNames} (Response's
 * constructor does this automatically).
 *
 * The row is iterable — `for (const v of row) ...` yields decoded
 * column values (same as repeated `row.get(i)`).
 */
export declare class Row implements Iterable<any> {
    readonly values: any[];
    readonly types: PropertyType[];
    /**
     * Column names for name-based access. Injected by the parent Response
     * constructor so that `row.getByName('col')` works without going
     * through Response.getByName(row, 'col').
     */
    columnNames: readonly string[];
    constructor(values: any[], types?: PropertyType[]);
    /** Get the value at the given column index */
    get(index: number): any;
    /**
     * Get the value for the given column name. Requires `columnNames` to
     * have been populated by the parent Response.
     */
    getByName(name: string): any;
    /** Returns true if this row knows the given column name. */
    has(name: string): boolean;
    /** Number of columns in this row. */
    get length(): number;
    /** Iterate over decoded column values. */
    [Symbol.iterator](): IterableIterator<any>;
    /**
     * Formatted representation. When `columnNames` is populated:
     *   `Row(name1=value1, name2=value2)`
     * Otherwise:
     *   `Row(value0, value1)`
     * Mirrors the Python driver's `repr(row)` layout.
     */
    toString(): string;
    /**
     * Structural equality: same column names (or both empty) AND decoded
     * column values compare equal pairwise. Mirrors Python `Row.__eq__`.
     * Uses JSON.stringify for nested value comparison — adequate for the
     * primitive/object types decoded from the wire.
     */
    equals(other: Row): boolean;
    /** Get the PropertyType at the given column index */
    getType(index: number): PropertyType;
    /** Get the value at the given column index as a string */
    getString(index: number): string;
    /** Get the value at the given column index as a number */
    getNumber(index: number): number;
    /** Get the value at the given column index as a boolean */
    getBoolean(index: number): boolean;
}
/**
 * Represents a single column's data from the response.
 * Allows chaining operations like resp.alias("n").asNodes() or resp.get(0).asNodes().
 */
export declare class AliasResult {
    private readonly aliasName;
    private readonly columnIdx;
    private readonly response;
    constructor(aliasName: string, columnIdx: number, response: Response);
    /** Get the alias name */
    get alias(): string;
    /** Get the column index */
    get columnIndex(): number;
    /**
     * Extract nodes from the aliased column with schema info.
     * Throws TypeError if the column contains non-NODE types.
     */
    private collectNode;
    private collectEdge;
    /**
     * Extract nodes from the aliased column with schema info.
     * Supports both direct NODE columns and LIST of NODE columns
     * (e.g., group variables from quantified patterns).
     */
    asNodes(): NodeResult;
    /**
     * Extract edges from the aliased column with schema info.
     * Supports both direct EDGE columns and LIST of EDGE columns
     * (e.g., group variables from quantified patterns).
     */
    asEdges(): EdgeResult;
    /**
     * Extract paths from the aliased column.
     * Throws TypeError if the column contains non-PATH types.
     */
    asPaths(): Path[];
    /** Convert the aliased column to a single-column table */
    asTable(): Table;
    private unwrapGqldbTable;
    /** Extract scalar or list attribute values from the aliased column */
    asAttr(): Attr;
    /** Extract raw JavaScript values from the aliased column */
    asValues(): any[];
    private buildSchemaFromNode;
    private buildSchemaFromEdge;
    private inferPropertyType;
}
/** Represents the result of a GQL query */
export declare class Response {
    readonly columns: string[];
    readonly rows: Row[];
    readonly rowCount: number;
    readonly hasMore: boolean;
    readonly warnings: string[];
    readonly rowsAffected: number;
    /**
     * Session's current graph after this RPC executed, as authoritatively
     * reported by the server. Always populated on success against new
     * servers (covers single/compound USE GRAPH at any position,
     * last-write-wins). Empty when running against a pre-fix server, in
     * which case the driver falls back to its USE GRAPH text-parsing path
     * internally to keep the local default-graph cache in sync.
     */
    readonly currentGraph: string;
    /**
     * Server-side timing (nanoseconds), read from the engine's ResultSet.
     * Network / client-side time is NOT included.
     *  - timeCostNs:    total wall-clock parse + plan + execute
     *  - diskCostNs:    subset spent in storage / LSM layer
     *  - computeCostNs: subset spent in the in-memory compute engine
     *                   (k-hop, shortest path, algo.* via topology
     *                   accelerator); 0 when compute is disabled or
     *                   the query path did not invoke the accelerator.
     * Old servers omit these proto3 fields → treat 0 as "not reported",
     * not "took zero time". Streaming queries populate only on the
     * final batch (hasMore=false), matching currentGraph / rowsAffected.
     */
    readonly timeCostNs: number;
    readonly diskCostNs: number;
    readonly computeCostNs: number;
    constructor(columns: string[], rows: Row[], rowCount: number, hasMore: boolean, warnings: string[], rowsAffected?: number, 
    /**
     * Session's current graph after this RPC executed, as authoritatively
     * reported by the server. Always populated on success against new
     * servers (covers single/compound USE GRAPH at any position,
     * last-write-wins). Empty when running against a pre-fix server, in
     * which case the driver falls back to its USE GRAPH text-parsing path
     * internally to keep the local default-graph cache in sync.
     */
    currentGraph?: string, 
    /**
     * Server-side timing (nanoseconds), read from the engine's ResultSet.
     * Network / client-side time is NOT included.
     *  - timeCostNs:    total wall-clock parse + plan + execute
     *  - diskCostNs:    subset spent in storage / LSM layer
     *  - computeCostNs: subset spent in the in-memory compute engine
     *                   (k-hop, shortest path, algo.* via topology
     *                   accelerator); 0 when compute is disabled or
     *                   the query path did not invoke the accelerator.
     * Old servers omit these proto3 fields → treat 0 as "not reported",
     * not "took zero time". Streaming queries populate only on the
     * final batch (hasMore=false), matching currentGraph / rowsAffected.
     */
    timeCostNs?: number, diskCostNs?: number, computeCostNs?: number);
    /** Check if the response has no rows */
    isEmpty(): boolean;
    /** Get the first row */
    first(): Row | undefined;
    /** Get the last row */
    last(): Row | undefined;
    /** Get the value for a column by name */
    getByName(row: Row, columnName: string): any;
    /** Iterate over all rows with a callback */
    forEach(fn: (row: Row, index: number) => void): void;
    /** Transform each row using a callback */
    map<T>(fn: (row: Row) => T): T[];
    /** Convert the response to an array of objects */
    toObjects(): Record<string, any>[];
    /** Convert the response to JSON */
    toJSON(): string;
    /** Get the single value from a single-row, single-column response */
    singleValue(): any;
    /** Get the single number value */
    singleNumber(): number;
    /** Get the single string value */
    singleString(): string;
    /** Iterator support */
    [Symbol.iterator](): Iterator<Row>;
    /** Get the number of rows */
    get length(): number;
    /**
     * Get an AliasResult for the specified column name.
     * Use this to extract data from a specific column by name.
     * Example: resp.alias("n").asNodes()
     */
    alias(columnName: string): AliasResult;
    /**
     * Get an AliasResult for the column at the specified index.
     * Use this to extract data from a specific column by index.
     * Example: resp.get(0).asNodes()
     */
    get(index: number): AliasResult;
    /**
     * @deprecated Use alias() or get() instead. This method will be removed in a future version.
     * Extract nodes from response with schema info.
     * Supports both NODE and LIST of NODE columns.
     */
    asNodes(): NodeResult;
    /**
     * @deprecated Use alias() or get() instead. This method will be removed in a future version.
     * Extract edges from response with schema info.
     * Supports both EDGE and LIST of EDGE columns.
     */
    asEdges(): EdgeResult;
    /**
     * @deprecated Use alias() or get() instead. This method will be removed in a future version.
     * Extract paths from response.
     * Paths are identified by PropertyType.PATH type in the TypedValue.
     */
    asPaths(): Path[];
    /**
     * @deprecated Use alias() or get() instead. This method will be removed in a future version.
     * Return response as generic table.
     * If response is a single TABLE column, unwraps the GqldbTable into proper headers/rows.
     */
    asTable(): Table;
    /**
     * @deprecated Use alias() or get() instead. This method will be removed in a future version.
     * Extract scalar or list attribute values
     */
    asAttr(columnName: string): Attr;
    private buildSchemaFromNode;
    private buildSchemaFromEdge;
    private inferPropertyType;
}
/** Result of an insert nodes operation */
export interface InsertNodesResult {
    success: boolean;
    nodeIds: string[];
    nodeCount: number;
    message: string;
}
/** Result of an insert edges operation */
export interface InsertEdgesResult {
    success: boolean;
    edgeIds: string[];
    edgeCount: number;
    message: string;
    skippedCount: number;
}
/** Configuration for the unified Export operation */
export interface ExportConfig {
    graphName: string;
    batchSize?: number;
    exportNodes?: boolean;
    exportEdges?: boolean;
    nodeLabels?: string[];
    edgeLabels?: string[];
    includeMetadata?: boolean;
}
/** Statistics for an export operation */
export interface ExportStats {
    nodesExported: number;
    edgesExported: number;
    bytesWritten: number;
    durationMs: number;
}
/** A chunk of exported data in JSON Lines format */
export interface ExportChunk {
    data: Buffer;
    isFinal: boolean;
    stats?: ExportStats;
}
/**
 * A batch of exported nodes
 * @deprecated Use export() with ExportConfig instead
 */
export interface ExportNodesResult {
    nodes: ExportedNode[];
    hasMore: boolean;
}
/**
 * A batch of exported edges
 * @deprecated Use export() with ExportConfig instead
 */
export interface ExportEdgesResult {
    edges: ExportedEdge[];
    hasMore: boolean;
}
/**
 * A node exported from the database
 * @deprecated Use export() with ExportConfig instead
 */
export interface ExportedNode {
    id: string;
    labels: string[];
    properties: Record<string, any>;
}
/**
 * An edge exported from the database
 * @deprecated Use export() with ExportConfig instead
 */
export interface ExportedEdge {
    id: string;
    label: string;
    fromNodeId: string;
    toNodeId: string;
    properties: Record<string, any>;
}
/** Represents a node in the graph database */
export interface Node {
    id: string;
    labels: string[];
    properties: Record<string, any>;
}
/** Represents an edge in the graph database */
export interface Edge {
    id: string;
    label: string;
    fromNodeId: string;
    toNodeId: string;
    properties: Record<string, any>;
}
/** Represents a path in the graph database */
export interface Path {
    nodes: Node[];
    edges: Edge[];
}
/** Result wrapper for nodes with schema information */
export interface NodeResult {
    nodes: Node[];
    schemas: Map<string, Schema>;
}
/** Result wrapper for edges with schema information */
export interface EdgeResult {
    edges: Edge[];
    schemas: Map<string, Schema>;
}