Welcome to GRIN’s documentation!

GRIN, which stands for Graph Retrieval INterface, is an interface designed to simplify the retrieval of graph data from various storage systems within GraphScope. It organizes common graph retrieval needs into categories such as topology, property, partition, and index, as well as compute-specific graph retrieval requirements as traits including traversal, filter, partition strategy, external/internal ids, etc.

GRIN offers APIs to fulfill these abstracted requirements. These APIs are defined in C and can be utilized in systems developed in various programming languages such as C++, Rust, and Java. GRIN organizes its APIs using categorized header files. Additionally, C macros are utilized by GRIN to allow storage systems that support GRIN to filter out APIs that they are unable to handle. This ensures compatibility while maximizing efficiency. The supported APIs are then implemented in the storage systems to prioritize efficient retrieval with minimal hidden overhead. By using GRIN, computing systems can utilize the supported APIs without worrying about performance concerns.

The documentation is organized as follows:

First, we introduce the basic concepts of GRIN, including the handle, API, and macros.

Next, we dive into the details of each API category, starting with the topology APIs. We then introduce the Labeled Property Graph (LPG) data model along with the property APIs. Within the LPG data model, we also address the additional topology-related APIs that handle the transition from a simple graph to a LPG. After that, we introduce the partition APIs, which are designed for partitioned graphs. Since graph partitioning is another layer on top of simple graphs and LPGs, we also provide additional topology and property-related APIs for this purpose. This three-level “stacking” of topology, property, and partition forms the fundamental organization of GRIN APIs.

Next, we introduce the index APIs, which are designed for graph indexing. Following that, we present the common APIs, which include the common functions of GRIN, such as schema message and error code. Finally, we end the per-category API introduction by presenting the extension APIs, which are a series of advanced APIs with default implementations that utilize the basic APIs of GRIN.

Lastly, we provide the developer guide of GRIN for developers to follow.

Contents:

• Getting Started
  • Get Graph from Storage
  • Handle
  • Return Values
  • Error Handling
• Graph Topology and APIs
  • Vertex List
  • Adjacent List
  • Edge List
• Property Graph and APIs
  • Labeled Property Graph
  • Schema-enabled Property Graph APIs
  • Schema-free Property Graph APIs
• Partitioned Graph and APIs
  • Partition Strategy
  • Partition APIs
• Graph Index and APIs
  • External ID
  • Internal ID
  • PK Indexing
  • Label Indexing
• Common Functional APIs
  • Error Code
  • Schema Message
• Extension APIs
  • List Chain
  • Indexed Adjacent List
  • Static Storage Feature Message
• Developer Guide For Storage Implementors
  • Implementation Principles
  • How to Implement GRIN
• Developer Guide For Users
  • How to Use GRIN
  • API Naming Rules