Data Operations

The GQLDB Node.js driver provides methods for inserting and deleting nodes and edges programmatically, without writing GQL queries.

Data Operation Methods

Inserting Nodes

insertNodes()

Insert one or more nodes into a graph:

TypeScript
import { GqldbClient, NodeData, InsertNodesResult } from 'gqldb-nodejs';

async function insertNodesExample(client: GqldbClient) {
  const nodes: NodeData[] = [
    {
      id: 'user1',
      labels: ['User'],
      properties: {
        name: 'Alice',
        age: 30,
        email: '[email protected]'
      }
    },
    {
      id: 'user2',
      labels: ['User'],
      properties: {
        name: 'Bob',
        age: 25
      }
    },
    {
      id: 'user3',
      labels: ['User', 'Admin'],  // Multiple labels
      properties: {
        name: 'Charlie',
        role: 'administrator'
      }
    }
  ];

  const result: InsertNodesResult = await client.insertNodes('myGraph', nodes);

  console.log('Success:', result.success);
  console.log('Node count:', result.nodeCount);
  console.log('Node IDs:', result.nodeIds);
  console.log('Message:', result.message);
}

NodeData Interface

TypeScript
interface NodeData {
  id: string;                        // Unique node identifier
  labels: string[];                  // One or more labels
  properties: Record<string, any>;   // Node properties
}

InsertNodesResult Interface

TypeScript
interface InsertNodesResult {
  success: boolean;
  nodeIds: string[];
  nodeCount: number;
  message: string;
}

Insert Options

Control node insertion behavior with InsertNodesConfig:

TypeScript
import { BulkCreateNodesOptions } from 'gqldb-nodejs';

async function insertWithOptions(client: GqldbClient) {
  const nodes: NodeData[] = [
    { id: 'user1', labels: ['User'], properties: { name: 'Alice' } }
  ];

  // Overwrite existing nodes with same ID
  const result = await client.insertNodes('myGraph', nodes, {
    options: {
      overwrite: true
    }
  });
}

Insert with Bulk Import Session

For high-throughput inserts, use bulk import:

TypeScript
async function insertWithBulkImport(client: GqldbClient) {
  // Start bulk import session
  const session = await client.startBulkImport('myGraph');

  try {
    // Insert nodes using the session
    const result = await client.insertNodes('myGraph', nodes, {
      bulkImportSessionId: session.sessionId
    });

    // End the session
    await client.endBulkImport(session.sessionId);
  } catch (error) {
    await client.abortBulkImport(session.sessionId);
    throw error;
  }
}

Inserting Edges

insertEdges()

Insert one or more edges into a graph:

TypeScript
import { GqldbClient, EdgeData, InsertEdgesResult } from 'gqldb-nodejs';

async function insertEdgesExample(client: GqldbClient) {
  const edges: EdgeData[] = [
    {
      id: 'e1',
      label: 'Follows',
      fromNodeId: 'user1',
      toNodeId: 'user2',
      properties: {
        since: '2024-01-15'
      }
    },
    {
      id: 'e2',
      label: 'Follows',
      fromNodeId: 'user2',
      toNodeId: 'user3',
      properties: {}
    },
    {
      id: 'e3',
      label: 'Knows',
      fromNodeId: 'user1',
      toNodeId: 'user3',
      properties: {
        strength: 0.8
      }
    }
  ];

  const result: InsertEdgesResult = await client.insertEdges('myGraph', edges);

  console.log('Success:', result.success);
  console.log('Edge count:', result.edgeCount);
  console.log('Edge IDs:', result.edgeIds);
  console.log('Skipped:', result.skippedCount);
  console.log('Message:', result.message);
}

EdgeData Interface

TypeScript
interface EdgeData {
  id: string;                        // Unique edge identifier
  label: string;                     // Edge label/type
  fromNodeId: string;                // Source node ID
  toNodeId: string;                  // Target node ID
  properties: Record<string, any>;   // Edge properties
}

InsertEdgesResult Interface

TypeScript
interface InsertEdgesResult {
  success: boolean;
  edgeIds: string[];
  edgeCount: number;
  message: string;
  skippedCount: number;  // Edges skipped due to missing nodes
}

Edge Insert Options

TypeScript
import { BulkCreateEdgesOptions } from 'gqldb-nodejs';

async function insertEdgesWithOptions(client: GqldbClient) {
  const edges: EdgeData[] = [
    { id: 'e1', label: 'Follows', fromNodeId: 'user1', toNodeId: 'user999', properties: {} }
  ];

  // Skip edges where source or target node doesn't exist
  const result = await client.insertEdges('myGraph', edges, {
    options: {
      skipInvalidNodes: true
    }
  });

  console.log('Inserted:', result.edgeCount);
  console.log('Skipped:', result.skippedCount);
}

Deleting Nodes

deleteNodes()

Delete nodes from a graph:

TypeScript
import { GqldbClient, DeleteResult } from 'gqldb-nodejs';

async function deleteNodesExample(client: GqldbClient) {
  // Delete specific nodes by ID
  const result1 = await client.deleteNodes('myGraph', ['user1', 'user2']);
  console.log(`Deleted ${result1.deletedCount} nodes`);

  // Delete nodes by label
  const result2 = await client.deleteNodes('myGraph', undefined, ['TempUser']);
  console.log(`Deleted ${result2.deletedCount} TempUser nodes`);

  // Delete nodes matching a condition
  const result3 = await client.deleteNodes(
    'myGraph',
    undefined,
    ['User'],
    'age < 18'  // WHERE clause
  );
  console.log(`Deleted ${result3.deletedCount} underage users`);
}

Parameters:

DeleteResult Interface

TypeScript
interface DeleteResult {
  success: boolean;
  deletedCount: number;
  message: string;
}

Deleting Edges

deleteEdges()

Delete edges from a graph:

TypeScript
async function deleteEdgesExample(client: GqldbClient) {
  // Delete specific edges by ID
  const result1 = await client.deleteEdges('myGraph', ['e1', 'e2']);
  console.log(`Deleted ${result1.deletedCount} edges`);

  // Delete edges by label
  const result2 = await client.deleteEdges('myGraph', undefined, 'TempRelation');
  console.log(`Deleted ${result2.deletedCount} TempRelation edges`);

  // Delete edges matching a condition
  const result3 = await client.deleteEdges(
    'myGraph',
    undefined,
    'Follows',
    'since < "2020-01-01"'
  );
  console.log(`Deleted ${result3.deletedCount} old follow relationships`);
}

Parameters:

Error Handling

TypeScript
import {
  InsertFailedError,
  DeleteFailedError,
  GraphNotFoundError
} from 'gqldb-nodejs';

async function safeDataOperations(client: GqldbClient) {
  try {
    await client.insertNodes('myGraph', nodes);
  } catch (error) {
    if (error instanceof InsertFailedError) {
      console.error('Insert failed:', error.message);
    } else if (error instanceof GraphNotFoundError) {
      console.error('Graph does not exist');
    } else {
      throw error;
    }
  }

  try {
    await client.deleteNodes('myGraph', ['node1']);
  } catch (error) {
    if (error instanceof DeleteFailedError) {
      console.error('Delete failed:', error.message);
    }
  }
}

Complete Example

TypeScript
import { GqldbClient, createConfig, NodeData, EdgeData } from 'gqldb-nodejs';

async function main() {
  const client = new GqldbClient(createConfig({
    hosts: ['192.168.1.100:9000']
  }));

  try {
    await client.login('admin', 'password');

    // Create test graph
    await client.createGraph('dataOpsDemo');

    // Insert users
    const users: NodeData[] = [
      { id: 'alice', labels: ['User'], properties: { name: 'Alice', age: 30 } },
      { id: 'bob', labels: ['User'], properties: { name: 'Bob', age: 25 } },
      { id: 'charlie', labels: ['User'], properties: { name: 'Charlie', age: 35 } },
      { id: 'temp1', labels: ['TempUser'], properties: { name: 'Temp1' } },
      { id: 'temp2', labels: ['TempUser'], properties: { name: 'Temp2' } }
    ];

    const nodeResult = await client.insertNodes('dataOpsDemo', users);
    console.log(`Inserted ${nodeResult.nodeCount} users`);

    // Insert relationships
    const relationships: EdgeData[] = [
      { id: 'r1', label: 'Follows', fromNodeId: 'alice', toNodeId: 'bob', properties: {} },
      { id: 'r2', label: 'Follows', fromNodeId: 'bob', toNodeId: 'charlie', properties: {} },
      { id: 'r3', label: 'Knows', fromNodeId: 'alice', toNodeId: 'charlie', properties: { years: 5 } }
    ];

    const edgeResult = await client.insertEdges('dataOpsDemo', relationships);
    console.log(`Inserted ${edgeResult.edgeCount} relationships`);

    // Delete temporary users
    const deleteResult = await client.deleteNodes('dataOpsDemo', undefined, ['TempUser']);
    console.log(`Deleted ${deleteResult.deletedCount} temporary users`);

    // Verify remaining data
    await client.useGraph('dataOpsDemo');
    const countResponse = await client.gql('MATCH (n) RETURN count(n)');
    console.log(`Remaining nodes: ${countResponse.singleNumber()}`);

    // Clean up
    await client.dropGraph('dataOpsDemo');

  } finally {
    await client.close();
  }
}

main().catch(console.error);