Custom Graphs

This guide will introduce the concept of Custom Graphs and how to create and manage them.

As outlined in the Graph concept page, there are two classes of Graph instances:

The Global Graph: This is the default, familiar graph, encompassing all connections to date.
Custom Graphs: These are app-specific graphs, accessible openly or governed by Graph Rules.

Create a Custom Graph

To create a Graph, follow these steps.

You MUST be authenticated as Builder to create a Graph.

Create Graph Metadata

First, construct a Graph Metadata object with the necessary content.

TS/JS
JSON Schema

Use the @lens-protocol/metadata package to construct a valid GraphMetadata object:

Exampleimport { graph } from "@lens-protocol/metadata";
const metadata = graph({  name: "XYZ",  title: "Not Just Another Graph… or is it?",  description: "My custom graph description",});

Upload Graph Metadata

Next, upload the Graph Metadata object to a public URI.

import { storageClient } from "./storage-client";
const { uri } = await storageClient.uploadAsJson(metadata);
console.log(uri); // e.g., lens://4f91ca…

This example uses Lens Storage to host the Metadata object. See the Lens Metadata Standards guide for more information on hosting Metadata objects.

Deploy Graph Contract

Next, deploy the Lens Graph smart contract.

TypeScript
GraphQL

Use the createGraph action to deploy the Lens Graph smart contract.

import { uri } from "@lens-protocol/client";import { createGraph } from "@lens-protocol/client/action";
const result = await createGraph(sessionClient, {  metadataUri: uri("lens://4f91ca…"),});

To learn more about how to use Graph Rules, see the Graph Rules guide.

Handle Result

TypeScript
GraphQL

Finally, handle the result using the adapter for the library of your choice:

import { handleOperationWith } from "@lens-protocol/client/viem";
// …
const result = await createGraph(sessionClient, {  metadataUri: uri("lens://4f91…"), // the URI from the previous step}).andThen(handleOperationWith(walletClient));

See the Transaction Lifecycle guide for more information on how to determine the status of the transaction.

Fetch a Graph

TypeScript
GraphQL
React

Use the fetchGraph action to fetch a single Graph by address or by transaction hash.

import { evmAddress } from "@lens-protocol/client";import { fetchGraph } from "@lens-protocol/client/actions";import { client } from "./client";
const result = await fetchGraph(client, {  address: evmAddress("0x1234…"),});
if (result.isErr()) {  return console.error(result.error);}
const graph = result.value;

Search Graphs

TypeScript
GraphQL

Use the paginated fetchGraphs action to search for graphs.

import { fetchGraphs } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await fetchGraphs(client, {  filter: {    searchBy: "graphName",  },});
if (result.isErr()) {  return console.error(result.error);}
// items: Array<Graph>const { items, pageInfo } = result.value;

Continue with the Pagination guide for more information on how to handle paginated results.

Access Control

The Graph contract supports two roles: Owner and Administrator.

Administrators can:

Update the Graph Metadata
Update the Graph Rules
Update the Graph Extra Data

The Owner can do everything the administrators can do, plus transfer ownership of the Graph to another address.

See the Team Management guide for more information on how to manage these roles.