Getting Started¶

Welcome to GraphScope Interactive! This guide will walk you through the process of setting up and running your first queries with our system.

Preparation¶

Make sure GraphScope Interactive is installed before proceeding on. If not, please follow installation to install the latest release.

Administrative tool: GraphScope Interactive offers an administrative tool of gsctl to help manage the Interactive service. For an in-depth guide on how to use this tool, please visit the page of administrative tool (TODO: add documentation for gsctl).
Graph Data: By default, GraphScope Interactive uses Tinkerpop’s modern graph to get you started. However, if you wish to configure your own graph and load your data, you can refer to the page of using custom graph_data for detailed steps.
Configurations: The service can be configured using a yaml file. For a detailed breakdown of all configurable items, please refer to the page of configurations.
Stored Procedures: GraphScope Interactive allows users to register stored procedures from both Cypher and C++ files. For more information on this, please refer to the page for stored procedures.

Install Interactive¶

See Installation Guide for instructions on how to install and deploy Interactive.

Connect to Interactive Service¶

You could connect the coordinator via gsctl.

gsctl connect --coordinator-endpoint http://127.0.0.1:8080
# change the port number if you have customized the coordinator port.

Check Service Status¶

After connecting to the Interactive Service, you can now view what we have initially for you.

gsctl ls -l

Actually, a builtin graph is provided with name gs_interactive_default_graph. Now you can switch to the graph context:

gsctl use GRAPH gs_interactive_default_graph
gsctl service status # show current service status

As seen from the output, the Interactive service is already running on the built-in graph.

Create a Stored Procedure¶

We proceed to create a stored procedure by defining a procedure with a YAML configuration: procedure.yaml.

name: test_procedure
description: "Ths is a test procedure"
query: "MATCH (n) RETURN COUNT(n);"
type: cypher

and create it via

gsctl create storedproc -f ./procedure.yaml

This step may take a while, since code generation and compilation is invoked. Finally, the id of the stored procedure(currently the name of the procedure) is returned, you can display the detail of the stored procedure with the following command.

gsctl desc storedproc test_procedure

You may notice that the value ofrunnable field is false, we need to restart service to enable it.

Restart the service¶

The stored procedure will not be able to serve requests until we restart the service.

gsctl service restart 

After the service is restarted, check the runnable field; it should be set to true.

gsctl desc storedproc test_procedure

Call the Stored Procedure¶

You have two options to call the stored procedure, one is through Interactive SDK, and the other is through the native tools of Cypher.

Call the Stored Procedure via Interactive SDK¶

You can call the stored procedure via Interactive Python SDK. (Make sure environment variables are set correctly, see above session).

export INTERACTIVE_ADMIN_ENDPOINT=http://127.0.0.1:7777
export INTERACTIVE_STORED_PROC_ENDPOINT=http://127.0.0.1:10000
export INTERACTIVE_CYPHER_ENDPOINT=neo4j://127.0.0.1:7687

Note

If you have customized the ports when deploying Interactive, remember to replace the default ports with your customized ports.

Install Interactive python SDK

pip3 install gs_interactive

and try to call the stored procedure.

from gs_interactive.client.driver import Driver
from gs_interactive.client.session import Session
from gs_interactive.models import *

driver = Driver()
with driver.getNeo4jSession() as session:
    result = session.run("CALL test_procedure() YIELD *;")
    for record in result:
        print(record)

Call the Stored Procedure via Neo4j-native Tools¶

You can also call the stored procedure via neo4j-native tools, like cypher-shell, neo4j-driver. Please refer to this document for connecting to cypher service.

./cypher-shell -a ${INTERACTIVE_CYPHER_ENDPOINT}

CALL test_procedure() YIELD *;

Submit Cypher Queries¶

GraphScope Interactive seamlessly integrates with the Neo4j ecosystem. You can establish a connection to the Interactive service using Neo4j’s Bolt connector and execute Cypher queries. Our implementation of Cypher queries aligns with the standards set by the openCypher project. For a detailed overview of the supported Cypher queries, please visit supported_cypher.

Follow the instructions in Connect-to-cypher-service to connect to the Cypher service using either the Python client or cypher-shell.

Note: Cypher queries submitted to GraphScope Interactive are compiled into a dynamic library for execution. While the initial compilation might take some time, the execution for subsequent uses (of the same query) will be much faster since it is cached by Interactive.

Close the connection¶

If you want to disconnect to coordinator, just type

gsctl close

Destroy the Interactive Instance¶

If you want to shutdown and uninstall the Interactive instance,

gsctl instance destroy --type interactive

This will remove all the graph and data for the Interactive instance.