@ultipa-graph/ultipa-driver/dist/types/convenience.d.ts

NodeJS SDK for Ultipa GQL

/**
 * Convenience API types for GQLDB Node.js driver.
 */
import type { Response } from '../response';
/** Distinguishes between node and edge operations */
export declare enum DBType {
    NODE = 0,
    EDGE = 1
}
/**
 * Controls the insert mode for GQL-based insert operations.
 *
 *   - `Normal`:    INSERT — error if `_id` already exists.
 *   - `Overwrite`: INSERT OVERWRITE — REPLACE existing entity wholesale
 *     on duplicate `_id`. Properties not in the write are LOST.
 *   - `Upsert`:    UPSERT — MERGE new properties into existing entity
 *     on duplicate `_id`. Properties not in the write are PRESERVED;
 *     properties in the write OVERWRITE existing values. Falls back to
 *     plain insert when no `_id` matches.
 *
 * `Overwrite` and `Upsert` are different semantics on existing rows.
 * Choose `Upsert` (merge) for partial-update workloads where you don't
 * want to lose existing fields; choose `Overwrite` (replace) for
 * known-clean re-ingest of an entity's full state.
 */
export declare enum InsertType {
    Normal = 0,
    Overwrite = 1,
    Upsert = 2
}
/** Label info from SHOW LABELS.
 *
 * GQL supports multi-label nodes (e.g. (n:Person:Employee)), so the
 * server returns labels as a list even when there is only one.
 */
export interface LabelInfo {
    labels: string[];
    type: string;
}
/** Node type info from SHOW NODE TYPES */
export interface NodeTypeInfo {
    name: string;
    properties: ConvPropertyDef[];
}
/** Edge type info from SHOW EDGE TYPES */
export interface EdgeTypeInfo {
    name: string;
    properties: ConvPropertyDef[];
}
/** Label definition used when creating closed graphs */
export interface LabelDef {
    name: string;
    properties: ConvPropertyDef[];
}
/** Property definition for convenience API (uses string type name) */
export interface ConvPropertyDef {
    name: string;
    type: string;
}
/** Property in an index definition */
export interface IndexProperty {
    name: string;
    prefixLength?: number;
}
/** Index info from SHOW INDEX */
export interface IndexInfo {
    indexName: string;
    entityType: string;
    label: string;
    property: string;
    prefixLength?: number;
    status: string;
    progress: string;
    indexedCount: number;
    totalCount: number;
    error: string;
}
/** Fulltext index info from SHOW FULLTEXT */
export interface FulltextInfo {
    indexName: string;
    entityType: string;
    schemaName: string;
    properties: string;
    analyzer: string;
    status: string;
    docCount: number;
    progress: string;
}
/** Task info from SHOW TASKS */
export interface TaskInfo {
    taskId: string;
    type: string;
    query: string;
    algoName: string;
    status: string;
    startedAt: string;
    progress: string;
    parameters: string;
    nodesWritten: number;
    computeTimeMs: number;
    writeTimeMs: number;
}
/** Process info from TOP */
export interface ProcessInfo {
    queryId: string;
    queryText: string;
    startTime: string;
    durationMs: number;
    status: string;
}
/** Graph statistics from db.stats() */
export interface GraphStats {
    graphName: string;
    nodeCount: number;
    edgeCount: number;
    labelCounts: Record<string, number>;
    edgeLabelCounts: Record<string, number>;
    nodePropertyStats: Record<string, Record<string, number>>;
    edgePropertyStats: Record<string, Record<string, number>>;
}
/** Response for GQL-based insert operations */
export interface InsertGqlResponse {
    rowsAffected: number;
}
/** Algorithm info from SHOW ALGOS */
export interface AlgoInfo {
    name: string;
    description: string;
    version: string;
    parameters: string;
}
/**
 * One stage row from a CALL ai.read / ai.gql YIELD stream.
 * Stage names include: start, routing, intent_extraction, describe_algorithm,
 * generation, validation, execution, final, error.
 */
export interface AiStage {
    stage: string;
    detail: string;
    elapsedMs: number;
    tokensInput: number;
    tokensOutput: number;
    tokensCached: number;
    /** Stage-specific payload (polymorphic JSON from server). */
    data: any;
}
/**
 * Result of a client.aiRead() / client.aiGql() call.
 *
 * For aiRead: `data` is the Response from re-executing the generated GQL.
 * For aiGql:  `data` is always null (generation-only; caller reruns manually).
 * On AI-side errors, `success=false`, `error` is populated, and `data` is null.
 */
export interface AiReadResult {
    stages: AiStage[];
    generatedGql: string | null;
    data: Response | null;
    success: boolean;
    error: string | null;
    totalElapsedMs: number;
    totalTokensInput: number;
    totalTokensOutput: number;
    totalTokensCached: number;
}
/**
 * Parse a comma-separated property definition string like "age INTEGER, name STRING"
 * into an array of ConvPropertyDef.
 */
export declare function parsePropertyString(s: string): ConvPropertyDef[];
/**
 * Convert a ConvPropertyDef type string to its GQL representation.
 * If the type is already a valid GQL type name, returns it as-is (uppercased).
 */
export declare function propertyTypeToGQL(typeName: string): string;
/**
 * Build a GQL property definition string like "{age INT64, name STRING}" from ConvPropertyDef[].
 */
export declare function buildPropertyDefString(props: ConvPropertyDef[]): string;
/**
 * Build the property list for CREATE INDEX, e.g. "prop1, prop2(10)".
 */
export declare function buildIndexPropertyString(props: IndexProperty[]): string;
/**
 * Format a JavaScript value as a GQL literal for INSERT statements.
 */
export declare function formatGqlValue(v: any): string;
/**
 * Build a GQL property value map like "{name: 'Alice', age: 30}" from a Record.
 */
export declare function buildPropertiesValueString(props: Record<string, any>): string;
/**
 * Return "USE GRAPH <name>\n" if graphName is non-empty, otherwise "".
 */
export declare function useGraphPrefix(graphName: string): string;
/**
 * Convert DBType to GQL keyword "NODE" or "EDGE".
 */
export declare function dbTypeToKeyword(dt: DBType): string;