@or-sdk/graph v1.7.12

Graphs SDK

The @or-sdk/graphs package provides a client for working with the Graphs system in OneReach.ai. With this client, you can perform operations such as creating graphs, executing queries, managing graph properties, and working with saved queries.

Concepts

Graph

A graph is a data structure that consists of nodes and relationships between those nodes. In the Graphs system, a graph can represent various types of entities and their relationships, allowing you to organize and structure data in a way that represents real-world scenarios.

Node

A node is an individual entity within a graph that represents a single data item. Nodes can have properties that store information about the entity as key-value pairs. They can also have one or more labels, which help to classify nodes into groups or categories.

Relationship

A relationship is a connection between two nodes in a graph. It represents how the entities are related or connected. Relationships can have properties that store information about the connection as key-value pairs. They also have a relationship type, which helps to classify the relationship based on its purpose or meaning.

Query

A query is a statement that is used to interact with the Graphs system, including creating, updating, or retrieving data from a graph. The query language used in the OneReach.ai Graphs system is based on Cypher, which is a powerful and expressive declarative graph query language.

Installation

To install the package, run the following command:

$ npm install @or-sdk/graphs

Usage

To use the Graphs client, you need to create an instance of the class with the appropriate configuration options. You can either provide the direct API URL or the service discovery URL. Here is an example:

import { Graphs } from '@or-sdk/graphs';

// with direct api url
const graphs = new Graphs({
  token: 'my-account-token-string',
  graphUrl: 'http://example.graphs/endpoint'
});

// with service discovery(slower)
const graphs = new Graphs({
  token: 'my-account-token-string',
  discoveryUrl: 'http://example.graphs/endpoint'
});

Once you have an instance of the Graphs client, you can use its methods to interact with the OneReach.ai Graphs system. The available methods are:

query

Execute a query in a graph to retrieve, create, or manipulate data stored in the graph.

Params

• query: ExecuteQueryArgs - The query object containing the graph name, the query string, and optional query parameters

Example

In this example, the query method executes a Cypher query to match nodes with the label "Place" where the name property equals "CoffeePlace", and returns the matching nodes.

const results = await graphs.query<{ p: Place }>({
  graph: 'places',
  query: 'MATCH (p: Place) WHERE p.name = $name RETURN p',
  params: { name: 'CoffeePlace' },
});

// Example response
[
  {
    p: {
      id: 1,
      labels: ['Place'],
      properties: {
        name: 'CoffeePlace',
        description: 'A cozy place for coffee lovers',
        lat: 40.7128,
        lng: -74.0060,
      },
    },
  },
]

transaction

Execute a set of queries in a transaction in a specified graph. Transactions are used to perform multiple operations atomically, meaning that if any of the operations fail, all operations in the transaction are rolled back, ensuring data consistency.

Params

• graph: string - The name of the graph to execute the transaction in
• queries: ExecuteTransactionArgs[] - The set of queries to be run in the transaction

Example

In this example, the transaction method executes two Cypher queries in a transaction to create two new nodes with the label "Place" and names "place1" and "place2" respectively.

const res = await graphs.transaction('places', [
  {
    query: 'CREATE (p: Place { name: "place1" })',
  },
  {
    query: 'CREATE (p: Place { name: $name })',
    params: { name: 'place2' },
  }
]);

In the event that the second query fails for some reason (for example if a "Place" node with the name "place2" already exists), the transaction will be rolled back and the first node with the name "place1" will not be created.

createGraph

Create a new graph with a specified name and optional description and imageUrl.

Params

• graph: Graph - The graph object containing the name, and optional description and imageUrl

Example

In this example, the createGraph method creates a new graph with the name "places", description "A graph of places and their relationships", and an imageUrl for the graph's icon.

const result = await graphs.createGraph({
  name: 'places',
  description: 'A graph of places and their relationships',
  imageUrl: 'http://example.com/graph-icon.png',
});

// Example response
{
  ok: 1,
}

listGraphs

Retrieve a list of graphs from the Graphs system, optionally filtering by a graph name.

Params

• name: string (optional) - The name of the graph to search for.

Returns

• Promise<List<Graph>>: A promise containing a list of graph objects.

Example

In this example, the listGraphs method fetches a list of graphs from the Graphs system.

const graphsList = await graphs.listGraphs();

console.log(graphsList.items);
// Example output
// [
//   {
//     name: 'places',
//     description: 'A graph of places and their relationships',
//     imageUrl: 'http://example.com/graph-icon.png',
//   },
//   {
//     name: 'people',
//     description: 'A graph of people and their relationships',
//     imageUrl: 'http://example.com/people-graph-icon.png',
//   },
// ]

// If you want to search for a specific graph by name
const specificGraphsList = await graphs.listGraphs('places');

console.log(specificGraphsList.items);
// Example output
// [
//   {
//     name: 'places',
//     description: 'A graph of places and their relationships',
//     imageUrl: 'http://example.com/graph-icon.png',
//   },
// ]

The listGraphs method helps you fetch information about the available graphs or a specific graph by name so you can manage them or execute queries on them using other methods available in the SDK.

getGraphInfo

Retrieve detailed information about a graph, including its labels and relationship types, by specifying its name.

Params

• name: string - The name of the graph for which you want to obtain information.

Returns

• Promise<GraphInfo>: A promise containing information about the requested graph.

Example

In this example, the getGraphInfo method fetches information about the "places" graph.

const graphInfo = await graphs.getGraphInfo("places");

console.log(graphInfo);
// Example output
// {
//   name: 'places',
//   description: 'A graph of places and their relationships',
//   imageUrl: 'http://example.com/graph-icon.png',
//   labels: ['Place', 'City', 'Country'],
//   relationshipTypes: ['LOCATED_IN', 'CONNECTED_TO']
//   propertyKeys: ['lat', 'lon', 'name', 'zipCode']
// }

The getGraphInfo method allows you to retrieve detailed information about a specific graph, such as its labels and relationship types, so you can understand the structure of the graph and use this information when working with queries or managing the graph.

updateGraph

Update the properties of an existing graph in the Graphs system, such as the description or imageUrl.

Params

• graph: Graph - The graph object containing the name of the graph to update, and any properties (description or imageUrl) that you want to update.

Returns

• Promise<WriteResponse>: A promise containing an object with a property 'ok' indicating the success of the update operation.

Example

In this example, the updateGraph method updates the description and imageUrl properties of an existing graph named "places".

const updateResult = await graphs.updateGraph({
  name: 'places',
  description: 'An updated description for the places graph',
  imageUrl: 'http://example.com/updated-graph-icon.png',
});

console.log(updateResult);
// Example output
// { ok: 1 }

The updateGraph method helps you modify the properties of an existing graph in the Graphs system. Keep in mind that you need to provide the name property of the graph you want to update, along with any of the properties you want to modify (description or imageUrl).

deleteGraph

Delete a graph by its name from the Graphs system.

Params

• name: string - The name of the graph to delete.

Returns

• Promise<WriteResponse>: A promise containing a write response object indicating the success status of the operation.

Example

In this example, the deleteGraph method deletes a graph with the name "places" from the Graphs system.

const result = await graphs.deleteGraph('places');

console.log(result);
// Example output
// {
//   ok: 1,
// }

Using the deleteGraph method, you can remove a graph from the Graphs system if you no longer need it or if you want to clean up resources. Keep in mind that deleting a graph permanently removes its data and cannot be undone. Ensure you have proper backups or data exports before performing this operation.

saveQuery

Save a query to the Graphs system for future reuse. This allows you to store frequently used queries for easy access and execution.

Params

• graph: string - The name of the graph that the query belongs to.
• query: Query - The query object containing the name, query string, and optional description and parameters.

Returns

• Promise<WriteResponse>: A promise containing a write response object indicating the success of the operation.

Example

In this example, the saveQuery method saves a query to the Graphs system for the "places" graph. The query finds places with the label "Place" that have a name property equal to a given value.

const query: Query = {
  name: 'findPlaceByName',
  query: 'MATCH (p: Place) WHERE p.name = $name RETURN p',
  description: 'Find a place by its name',
  params: { name: 'string' },
};

const result = await graphs.saveQuery('places', query);

// Example response
// {
//   ok: 1,
// }

The saveQuery method makes it easy to store frequently used queries to the Graphs system, allowing you to execute them later without defining the query each time. You can also manage the saved queries using other methods available in the SDK, such as listQueries, getQuery, and deleteQuery.

listQueries

Retrieve a list of saved queries for a specific graph, optionally filtering by a query name.

Params

• graph: string - The name of the graph for which to list saved queries.
• name: string (optional) - The name of the query to search for.

Returns

• Promise<List<Query>>: A promise containing a list of saved query objects.

Example

In this example, the listQueries method fetches a list of saved queries for a graph named "places".

const queriesList = await graphs.listQueries('places');

console.log(queriesList.items);
// Example output
// [
//   {
//     name: 'find_place_by_name',
//     query: 'MATCH (p:Place) WHERE p.name = $name RETURN p',
//     description: 'Find a place by its name',
//     params: { name: 'string' },
//   },
//   {
//     name: 'find_nearby_places',
//     query: 'MATCH (p:Place) WHERE p.lat between $latMin and $latMax AND p.lng between $lngMin and $lngMax RETURN p',
//     description: 'Find nearby places based on latitude and longitude ranges',
//     params: { latMin: 'number', latMax: 'number', lngMin: 'number', lngMax: 'number' },
//   },
// ]

// If you want to search for a specific saved query by name
const specificQueriesList = await graphs.listQueries('places', 'find_place_by_name');

console.log(specificQueriesList.items);
// Example output
// [
//   {
//     name: 'find_place_by_name',
//     query: 'MATCH (p:Place) WHERE p.name = $name RETURN p',
//     description: 'Find a place by its name',
//     params: { name: 'string' },
//   },
// ]

The listQueries method allows you to fetch information about saved queries for a specific graph so you can execute them or manage them using other methods available in the SDK.

getQuery

Retrieve a single saved query by its name from a specified graph.

Params

• graph: string - The name of the graph to which the saved query belongs.
• name: string - The name of the saved query to fetch.

Returns

• Promise<Query>: A promise containing a query object with details of the saved query.

Example

In this example, the getQuery method retrieves a saved query named "find_places" from the "places" graph.

const query = await graphs.getQuery('places', 'find_places');

console.log(query);
// Example output
// {
//   name: 'find_places',
//   query: 'MATCH (p: Place) WHERE p.name = $name RETURN p',
//   description: 'Find places by name',
//   params: { name: 'string' },
// }

The getQuery method helps you fetch the details of a specific saved query from a graph so that you can review its functionality, update its properties, or delete it if necessary using other SDK methods.

deleteQuery

Delete a saved query from a graph in the Graphs system.

Params

• graph: string - The name of the graph the saved query belongs to.
• name: string - The name of the saved query to delete.

Returns

• Promise<WriteResponse>: A promise containing the write response indicating the success or failure of the deletion.

Example

In this example, the deleteQuery method deletes a saved query named "findPopularPlaces" from the "places" graph.

const result = await graphs.deleteQuery('places', 'findPopularPlaces');

console.log(result);
// Example output
// {
//   ok: 1,
// }

Use the deleteQuery method to maintain and manage your saved queries in a graph by deleting the ones that are no longer needed or relevant. This helps with keeping your Graphs system organized and efficient.