This is an automated email from the ASF dual-hosted git repository.
xiaokang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-graphar.git
The following commit(s) were added to refs/heads/main by this push:
new b45f5a1e feat(doc): add java info documents (#755)
b45f5a1e is described below
commit b45f5a1e461272ee0b223ede7ce1c1f420e35d7e
Author: Xiaokang Yang <[email protected]>
AuthorDate: Fri Sep 12 15:50:49 2025 +0800
feat(doc): add java info documents (#755)
* add java-info doc
* fix
* fix
* update README-zh-cn
* update
---
README-zh-cn.md | 19 +-
README.md | 18 +-
codecov.yml | 2 +-
docs/libraries/cpp/getting-started.md | 9 +-
docs/libraries/java/info/getting-started.md | 111 +++++++++++
.../java/{java.md => java-FFI/getting-started.md} | 6 +-
.../how_to_develop_java_ffi.md} | 8 +-
docs/libraries/java/java.md | 210 +--------------------
docs/libraries/spark/spark.md | 1 -
docs/specification/format.md | 83 +++++++-
maven-projects/info/README.md | 58 +++++-
11 files changed, 299 insertions(+), 226 deletions(-)
diff --git a/README-zh-cn.md b/README-zh-cn.md
index a27134b6..59472d97 100644
--- a/README-zh-cn.md
+++ b/README-zh-cn.md
@@ -205,12 +205,23 @@ GraphAr 提供了一组用于读取、写入和转换文件的库。目前，以
有关 Scala 与 Spark 库的详细信息，请参阅 [GraphAr Spark库](./maven-projects/spark)。
-### Java 库
+### Java (FFI) 库
-> [!NOTE]
-> Java 库正在开发中。
-GraphAr Java 库是通过绑定到 C++ 库（当前版本为v0.10.0）创建的，使用
[Alibaba-FastFFI](https://github.com/alibaba/fastFFI) 进行实现。有关 Java 库构建的详细信息，请参阅
[GraphAr Java库](./maven-projects/java)。
+> [!WARNING]
+> Java (FFI) 库已不再更新，最后版本依赖于 C++ 库 v0.12.0。
+
+GraphAr Java 库是通过绑定到 C++ 库（当前版本为v0.12.0）创建的，使用
[Alibaba-FastFFI](https://github.com/alibaba/fastFFI) 进行实现。有关 Java 库构建的详细信息，请参阅
[GraphAr Java库](./maven-projects/java)。
+
+
+### Java 库
+> [!NOTE]
+> Java 库正在开发中.
+
+java 库将由纯java开发，他将会包括下面的模块：
+- **[Java-Info](./maven-projects/info)**：负责从yaml文件中解析Graphinfo（schema）
+- **Java-io-XXX**：负责从不同存储格式读取图形数据（待实现）
+- **Java-Api-XXX**：为图形操作提供高级API（待实现）
### Python（PySpark）库
diff --git a/README.md b/README.md
index 35a2ce0d..e8b88321 100644
--- a/README.md
+++ b/README.md
@@ -417,17 +417,27 @@ See [GraphAr Spark
Library](./maven-projects/spark)
for details about the Scala with Spark library.
-### The Java Library
+### The Java (FFI) Library
-> [!NOTE]
-> The Java library is under development.
+> [!WARNING]
+> The Java (FFI) library is no longer being updated. The final version depends
on C++ library v0.12.0.
-The GraphAr Java library is created with bindings to the C++ library
+The GraphAr Java library was created with bindings to the C++ library
(currently at version v0.12.0), utilizing
[Alibaba-FastFFI](https://github.com/alibaba/fastFFI) for
implementation. See [GraphAr Java Library](./maven-projects/java) for
details about the building of the Java library.
+### The Java Library
+> [!NOTE]
+> The Java library is under development.
+
+Unlike java-FFI, the Java library will be implemented by pure java, which will
contain different modules:
+
+- **[java-info](./maven-projects/info)**: Responsible for parsing graphInfo
(schema) from YAML files
+- **java-io-xxx**: Responsible for reading graph data from different storage
formats (to be implemented)
+- **java-api-xxx**: Provides high level API for graph operations (to be
implemented)
+
### The Python with PySpark Library
> [!NOTE]
diff --git a/codecov.yml b/codecov.yml
index 3f391c24..39b49ba0 100644
--- a/codecov.yml
+++ b/codecov.yml
@@ -24,7 +24,7 @@ flags:
- "maven-projects/spark/"
pyspark:
paths:
- - "pyspark"
+ - "pyspark/"
java-info:
paths:
- "maven-projects/info/"
diff --git a/docs/libraries/cpp/getting-started.md
b/docs/libraries/cpp/getting-started.md
index c0403a77..d16cd261 100644
--- a/docs/libraries/cpp/getting-started.md
+++ b/docs/libraries/cpp/getting-started.md
@@ -290,6 +290,7 @@ id|:LABEL|name|url
...
1575|university|Paktia_University|http://dbpedia.org/resource/Paktia_University
```
+
At the beginning, we need to add label information into the `yml` file of
vertex. For this example, it should be as follows.
```yml
@@ -318,6 +319,7 @@ property_groups:
version: gar/v1
```
+
When you have the data ready, you can read the file into `arrow::Table` by
using arrow I/O function.
``` cpp
@@ -339,7 +341,9 @@ When you have the data ready, you can read the file into
`arrow::Table` by using
std::shared_ptr<arrow::Table> table;
table = reader->Read().ValueOrDie();
```
+
You can export label table to disk in parquet format, and read it back into
memory in the following way.
+
``` cpp
auto options_parquet_builder = WriterOptions::ParquetOptionBuilder();
options_parquet_builder.compression(arrow::Compression::type::UNCOMPRESSED);
@@ -360,12 +364,11 @@ You can export label table to disk in parquet format, and
read it back into memo
assert(reader->GetLabelChunk().status().ok());
assert(reader->next_chunk().ok());
```
+
### Using Label Filtering Functions
By calling the `graphar::VerticesCollection::verticesWithLabel` or
`graphar::VerticesCollection::verticesWithMultipleLabels` API, we can specify a
certain type of vertices on a certain graph, then filter out all vertices that
match one or more labels. Here we introduce several examples of using label
filtering.
-
-
```cpp
graph_info = ...
auto vertex_info = graph_info->GetVertexInfo("organisation");
@@ -403,8 +406,8 @@ By calling the
`graphar::VerticesCollection::verticesWithLabel` or `graphar::Ver
```
-Notice that, if the first two queries are executed successively, the result is
equivalent to the third query.
+Notice that, if the first two queries are executed successively, the result is
equivalent to the third query.
### Working with Cloud Storage (S3, OSS)
diff --git a/docs/libraries/java/info/getting-started.md
b/docs/libraries/java/info/getting-started.md
new file mode 100644
index 00000000..27e88e5d
--- /dev/null
+++ b/docs/libraries/java/info/getting-started.md
@@ -0,0 +1,111 @@
+---
+id: getting-started
+title: Getting Started with Info Module
+sidebar_position: 1
+---
+
+# Getting Started with Info Module
+
+This article is a quick guide that explains how to work with GraphAr Java Info
module. The Info module is part of the pure Java implementation of GraphAr and
provides capabilities for parsing graph metadata (schema) from YAML files.
+
+## metadata Files
+
+GraphAr uses a group of information files to save the metadata for a graph.
For more information, see [GraphAr Format
Specification](https://graphar.apache.org/docs/specification/format#information-files).
+
+`java-info` module provides the function of reading and parsing information
files
+
+## How to Use GraphAr Java Info Module
+
+### Load graph Info
+
+#### Load GraphInfo from local file system
+
+Here's a simple example of how to use the java-info module:
+
+```java
+import org.apache.graphar.info.GraphInfo;
+import org.apache.graphar.info.loader.GraphInfoLoader;
+import
org.apache.graphar.info.loader.impl.LocalFileSystemStreamGraphInfoLoader;
+import java.nio.file.Paths;
+
+// Load graph info from a YAML file
+GraphInfoLoader loader = new LocalFileSystemStreamGraphInfoLoader();
+GraphInfo graphInfo =
loader.loadGraphInfo(Paths.get("path/to/graph.yml").toUri());
+
+// Access graph metadata
+String graphName = graphInfo.getName();
+List<VertexInfo> vertices = graphInfo.getVertexInfos();
+List<EdgeInfo> edges = graphInfo.getEdgeInfos();
+
+// Access vertex metadata
+VertexInfo personVertex = vertices.get(0);
+String vertexType = personVertex.getType();
+long chunkSize = personVertex.getChunkSize();
+
+// Access edge metadata
+EdgeInfo knowsEdge = edges.get(0);
+String edgeType = knowsEdge.getEdgeType();
+boolean isDirected = knowsEdge.isDirected();
+```
+
+#### Custom YAML Loader Implementation
+
+The java-info module requires users to implement their own YAML reading
interface, because we typically face data lakes where data may be stored
anywhere (local file or HDFS or S3 or OSS...). Users can implement one or more
of `StringGraphInfoLoader`, `ReaderGraphInfoLoader`, or `StreamGraphInfoLoader`
(a local file system implementation is already provided).
+
+Here's an example of how to implement a custom YAML loader by extending the
`StringGraphInfoLoader` abstract class:
+
+```java
+import org.apache.graphar.info.loader.StringGraphInfoLoader;
+import java.io.IOException;
+import java.net.URI;
+
+public class MyStringGraphInfoLoader extends StringGraphInfoLoader {
+ @Override
+ public String readYaml(URI uri) throws IOException {
+ // Implement your custom logic to read YAML from any source
+ // This example shows reading from a database, but it could be HTTP,
S3, HDFS, etc.
+
+ // Example: Read from a database based on URI path
+ String path = uri.getPath();
+ // Query database for YAML content
+ return readYamlFromDatabase(path);
+ }
+
+ private String readYamlFromDatabase(String path) throws IOException {
+ // Your database access logic here
+ // This is just a placeholder implementation
+ // In a real implementation, you would connect to your database
+ // and retrieve the YAML content based on the path
+
+ // For example:
+ // Connection conn = DriverManager.getConnection(dbUrl, username,
password);
+ // PreparedStatement stmt = conn.prepareStatement("SELECT yaml_content
FROM graphs WHERE id = ?");
+ // stmt.setString(1, path);
+ // ResultSet rs = stmt.executeQuery();
+ // if (rs.next()) {
+ // return rs.getString("yaml_content");
+ // }
+
+ // Placeholder return
+ return "name: example\ntype: graph\nversion: v1";
+ }
+}
+
+// Usage of the custom loader
+MyStringGraphInfoLoader customLoader = new MyStringGraphInfoLoader();
+GraphInfo graphInfo =
customLoader.loadGraphInfo(URI.create("db://mydatabase/graphs/graph1/graph.yml"));
+```
+
+### Building
+
+To build the graphar-info module, you need:
+
+- JDK 11 or higher
+- Maven 3.5 or higher
+
+Build the module with Maven:
+
+```bash
+cd maven-projects/info
+mvn clean install
+```
\ No newline at end of file
diff --git a/docs/libraries/java/java.md
b/docs/libraries/java/java-FFI/getting-started.md
similarity index 98%
copy from docs/libraries/java/java.md
copy to docs/libraries/java/java-FFI/getting-started.md
index 95169569..9b661df1 100644
--- a/docs/libraries/java/java.md
+++ b/docs/libraries/java/java-FFI/getting-started.md
@@ -1,7 +1,7 @@
---
-id: java
-title: Java Library
-sidebar_position: 2
+id: getting-started
+title: Getting Started with java FFI Module
+sidebar_position: 1
---
## Overview
diff --git a/docs/libraries/java/how_to_develop_java.md
b/docs/libraries/java/java-FFI/how_to_develop_java_ffi.md
similarity index 96%
rename from docs/libraries/java/how_to_develop_java.md
rename to docs/libraries/java/java-FFI/how_to_develop_java_ffi.md
index e279c91e..b310c050 100644
--- a/docs/libraries/java/how_to_develop_java.md
+++ b/docs/libraries/java/java-FFI/how_to_develop_java_ffi.md
@@ -1,7 +1,7 @@
---
-id: how_to_develop_java
-title: How to Develop Java Library
-sidebar_position: 1
+id: how_to_develop_java_ffi
+title: How to Develop Java FFI Library
+sidebar_position: 2
---
## Introduction
@@ -75,7 +75,7 @@ More about usage of CMake, please refer to
## Building GraphAr Java
Please refer to
-[GraphAr Java Library user guide](java.md).
+[GraphAr Java Library user guide](getting-started).
## How To Test
diff --git a/docs/libraries/java/java.md b/docs/libraries/java/java.md
index 95169569..5598b7c0 100644
--- a/docs/libraries/java/java.md
+++ b/docs/libraries/java/java.md
@@ -4,212 +4,16 @@ title: Java Library
sidebar_position: 2
---
-## Overview
+# Java Library
-Based on an efficient FFI for Java and C++ called
-[fastFFI](https://github.com/alibaba/fastFFI), the GraphAr Java
-library allows users to write Java for generating, loading and
-transforming GraphAr format files. It consists of several components:
+The GraphAr Java library is currently available in two versions:
-- **Information Classes**: As same with in the C++ library, the
- information classes are implemented to construct and access the meta
- information about the **graphs**, **vertices** and **edges** in
- GraphAr.
+## 1. Java-FFI Version (Deprecated)
-- **Writers**: The GraphAr Java writer provides a set of interfaces
- that can be used to write Apache Arrow VectorSchemaRoot into GraphAr format
- files. Every time it takes a VectorSchemaRoot as the logical table
- for a type of vertices or edges, then convert it to ArrowTable, and
- then dumps it to standard GraphAr format files (CSV, ORC or Parquet files)
under
- the specific directory path.
+This version is implemented using FastFFI to bridge Java and C++ code. While
functional, this version is no longer being actively updated or maintained.
-- **Readers**: The GraphAr Java reader provides a set of interfaces
- that can be used to read GraphAr format files. It reads a collection of
vertices
- or edges at a time and assembles the result into the ArrowTable.
- Similar with the reader in the C++ library, it supports the users to
- specify the data they need, e.g., reading a single property group
- instead of all properties.
+## 2. Pure Java Version (Under Development)
-## Get GraphAr Java Library
+This is the next generation of the GraphAr Java library, being actively
developed to provide a pure Java implementation without native dependencies.
-### Building from source
-
-Only support installing from source currently, but we will support
-installing from Maven in the future.
-
-Firstly, install llvm-11. `LLVM11_HOME` should point to the home of
-LLVM 11. In Ubuntu, it is at `/usr/lib/llvm-11`. Basically, the build
-procedure the following binary:
-
-- `$LLVM11_HOME/bin/clang++`
-- `$LLVM11_HOME/bin/ld.lld`
-- `$LLVM11_HOME/lib/cmake/llvm`
-
-Tips:
-
-- Use Ubuntu as example:
-
-```bash
-sudo apt-get install llvm-11 clang-11 lld-11 libclang-11-dev libz-dev -y
-export LLVM11_HOME=/usr/lib/llvm-11
-```
-
-- Or compile from source with this
[script](https://github.com/alibaba/fastFFI/blob/main/docker/install-llvm11.sh):
-
-```bash
-export LLVM11_HOME=/usr/lib/llvm-11
-export LLVM_VAR=11.0.0
-sudo ./install-llvm11.sh
-```
-
-Make the graphar-java-library directory as the current working
-directory:
-
-```bash
-git clone https://github.com/apache/incubator-graphar.git
-cd incubator-graphar
-git submodule update --init
-cd maven-projects/java
-```
-
-Compile package:
-
-```bash
-mvn clean install -DskipTests
-```
-
-This will build GraphAr C++ library internally for Java. If you already
installed GraphAr C++ library in your system,
-you can append this option to skip: `-DbuildGarCPP=OFF`.
-
-Then set GraphAr as a dependency in maven project:
-
-```xml
-<dependencies>
- <dependency>
- <groupId>org.apache.graphar</groupId>
- <artifactId>java</artifactId>
- <version>0.1.0</version>
- </dependency>
-</dependencies>
-```
-
-## How to use
-
-### Information classes
-
-The Java library for GraphAr provides distinct information classes for
-constructing and accessing meta information about graphs, vertices, and
-edges. These classes act as essential parameters for constructing
-readers and writers, and they can be built either from the existing meta
-files (in the Yaml format) or in-memory from scratch.
-
-To construct information from a Yaml file, please refer to the following
-example code.
-
-```java
-// read graph yaml and construct information
-String path = ...; // the path to the yaml file
-Result<StdSharedPtr<GraphInfo>> graphInfoResult = GraphInfo.load(path);
-if (!graphInfoResult.hasError()) {
- GraphInfo graphInfo = graphInfoResult.value().get();
- // use information classes
- StdVector<StdSharedPtr<@CXXReference VertexInfo>> vertexInfos =
graphInfo.getVertexInfos();
- StdVector<StdSharedPtr<@CXXReference EdgeInfo>> edgeInfos =
graphInfo.getEdgeInfos();
-}
-```
-
-See [test for
-graphinfo](https://github.com/apache/incubator-graphar/blob/main/maven-projects/java/src/test/java/org/apache/graphar/graphinfo)
-for the complete example.
-
-### Writers
-
-The GraphAr Java writers wrap C++ interfaces to write arrow::Table into GraphAr
-formatted files in a batch-import fashion. But arrow::Table is not easy
-to build in Java. Instead, the GraphAr Java library provide a static
-method to convert VectorSchemaRoot into arrow::Table. Warning: There are
-some problems concerning this method which lead to memory leaks. We will
-fix it or rewrite writers with Apache arrow Java.
-
-With the VertexWriter, users can specify a particular property group to
-be written into its corresponding chunks, or choose to write all
-property groups. For edge chunks, besides the meta data (edge info), the
-adjList type should also be specified. The adjList/properties can be
-written alone, or alternatively, all adjList, properties, and the offset
-(for CSR and CSC format) chunks can be written simultaneously.
-
-To utilize the GraphAr Java writer, please refer to the following example
-code.
-
-```java
-// common steps to construct VectorSchemaRoot
-String uri = "file:" + ...; // data source
-ScanOptions options = new ScanOptions(/*batchSize*/ 32768);
-StdSharedPtr<ArrowTable> table = null;
-try (BufferAllocator allocator = new RootAllocator();
- DatasetFactory datasetFactory =
- new FileSystemDatasetFactory(
- allocator, NativeMemoryPool.getDefault(),
FileFormat.PARQUET, uri);
- Dataset dataset = datasetFactory.finish();
- Scanner scanner = dataset.newScan(options);
- ArrowReader reader = scanner.scanBatches()) {
- while (reader.loadNextBatch()) {
- try (VectorSchemaRoot root = reader.getVectorSchemaRoot()) {
- // convert VectorSchemaRoot to ArrowTable
- table = ArrowTable.fromVectorSchemaRoot(allocator, root, reader);
- }
- }
-} catch (Exception e) {
- e.printStackTrace();
-}
-
-// construct writer object
-String path = ...; // file to be wrote
-StdString edgeMetaFile = StdString.create(path);
-StdSharedPtr<Yaml> edgeMeta = Yaml.loadFile(edgeMetaFile).value();
-StdSharedPtr<EdgeInfo> edgeInfo = EdgeInfo.load(edgeMeta).value();
-EdgeChunkWriter writer = EdgeChunkWriter.factory.create(
- edgeInfo, StdString.create("/tmp/"),
AdjListType.ordered_by_source);
-
-// write table with writer object
-writer.sortAndWriteAdjListTable(table, 0, 0); // Write adj list of vertex
chunk 0 to files
-```
-
-See [test for
-writers](https://github.com/apache/incubator-graphar/blob/main/maven-projects/java/src/test/java/org/apache/graphar/writers)
-for the complete example.
-
-### Readers
-
-The GraphAr Java reader provides an extensive set of interfaces to read
-GraphAr format files. It reads a collection of vertices or edges at a time as
-ArrowTable. Similar with the reader in C++ library, it supports the
-users to specify the data they need, e.g., a single property group.
-
-To utilize the GraphAr Java reader, please refer to the following example
-code.
-
-```java
-// construct vertex chunk reader
-graphInfo = ...; // load graph meta info
-StdString label = StdString.create("person");
-StdString propertyName = StdString.create("id");
- if (graphInfo.get().getVertexInfo(label).get() == null) {
- // throw Exception or do other things
- }
-StdSharedPtr<PropertyGroup> group =
-
graphInfo.get().getVertexInfo(label).get().getPropertyGroup(propertyName);
-
-Result<StdSharedPtr<VertexPropertyArrowChunkReader>> maybeReader =
-
GrapharStaticFunctions.INSTANCE.constructVertexPropertyArrowChunkReader(
- graphInfo, label, group);
-// check reader's status if needed
-StdSharedPtr<VertexPropertyArrowChunkReader> reader = maybeReader.value();
-Result<StdSharedPtr<ArrowTable>> result = reader.get().getChunk();
-// check table's status if needed
-StdSharedPtr<ArrowTable> table = result.value();
-```
-
-See [test for
-readers](https://github.com/apache/incubator-graphar/blob/main/maven-projects/java/src/test/java/org/apache/graphar/readers)
-for the complete example.
+Currently, only the `graphar-info` module has been implemented in pure Java,
which provides the ability to parse graph info (schema). Additional modules
such as IO and high level API will be provided progressively.
diff --git a/docs/libraries/spark/spark.md b/docs/libraries/spark/spark.md
index 76a5993b..196e743b 100644
--- a/docs/libraries/spark/spark.md
+++ b/docs/libraries/spark/spark.md
@@ -227,7 +227,6 @@ The Spark library for GraphAr supports reading and writing
data from/to cloud st
- [AWS S3](https://spark.apache.org/docs/latest/cloud-integration.html)
- [Aliyun
OSS](https://hadoop.apache.org/docs/stable/hadoop-aliyun/tools/hadoop-aliyun/index.html)
-
[test-graph-info]:
https://github.com/apache/incubator-graphar/blob/main/maven-projects/spark/graphar/src/test/scala/org/apache/graphar/TestGraphInfo.scala
[test-index-generator]:
https://github.com/apache/incubator-graphar/blob/main/maven-projects/spark/graphar/src/test/scala/org/apache/graphar/TestIndexGenerator.scala
[test-writer]:
https://github.com/apache/incubator-graphar/blob/main/maven-projects/spark/graphar/src/test/scala/org/apache/graphar/TestWriter.scala
diff --git a/docs/specification/format.md b/docs/specification/format.md
index 3859b5f1..b5a9ed9f 100644
--- a/docs/specification/format.md
+++ b/docs/specification/format.md
@@ -147,6 +147,9 @@ Take the "person knows person" edges to illustrate. Suppose
the vertex chunk siz
## Information files
GraphAr uses two kinds of files to store a graph: a group of Yaml files to
describe metadata information; and data files to store actual data for vertices
and edges.
+
+### Graph Information File
+
A graph information file which named "\<name\>.graph.yml" describes the meta
information for a graph whose name is \<name\>. The content of this file
includes:
- the graph name;
@@ -155,6 +158,22 @@ A graph information file which named "\<name\>.graph.yml"
describes the meta inf
- the version of GraphAr.
- extra information for the graph, could be used for user defined information.
+**An example of the graph information file is shown as follows**:
+
+```yaml
+name: ldbc_sample
+prefix: ./
+vertices:
+ - person.vertex.yml
+edges:
+ - person_knows_person.edge.yml
+version: gar/v1
+```
+
+In this example, it defines an example graph named "ldbc_sample", which
includes one type of vertices ("person") and one type of edges ("person knows
person").
+
+### Vertex Information File
+
A vertex information file which named "\<label\>.vertex.yml" defines a single
group of vertices with the same vertex label \<label\>, and all vertices in
this group have the same schema. The file defines:
- the vertex label;
@@ -163,6 +182,36 @@ A vertex information file which named
"\<label\>.vertex.yml" defines a single gr
- the property groups attached: each property group has its own file type and
the prefix for the path of its data files, it also lists all properties in this
group, with every property containing its own name, data type, flagging of
whether it is the primary key or not and flagging of whether it is nullable or
not for non-primary key properties;
- the version of GraphAr.
+**An example of the vertex information file is shown as follows**:
+
+```yaml
+type: person
+chunk_size: 100
+prefix: vertex/person/
+property_groups:
+ - properties:
+ - name: id
+ data_type: int64
+ is_primary: true
+ file_type: parquet
+ - properties:
+ - name: firstName
+ data_type: string
+ is_primary: false
+ - name: lastName
+ data_type: string
+ is_primary: false
+ - name: gender
+ data_type: string
+ is_primary: false
+ file_type: parquet
+version: gar/v1
+```
+
+In this example, the "person" vertices have two property groups. The first
group contains only one property (named "id") and the second group contains
three properties ("firstName", "lastName" and "gender").
+
+### Edge Information File
+
An edge information file which named "\<source label\>_\<edge
label\>_\<destination label\>.edge.yml" defines a single group of edges with
specific label for source vertex, destination vertex and the edge. It describes
the meta information for these edges, includes:
- the source/edge/destination labels;
@@ -173,13 +222,43 @@ An edge information file which named "\<source
label\>_\<edge label\>_\<destinat
- the property groups attached to the edge for all adjLists;
- the version of GraphAr.
+An example of the edge information file is shown as follows:
+
+```yaml
+src_type: person
+edge_type: knows
+dst_type: person
+chunk_size: 1024
+src_chunk_size: 100
+dst_chunk_size: 100
+directed: false
+prefix: edge/person_knows_person/
+adj_lists:
+ - ordered: false
+ aligned_by: src
+ file_type: parquet
+ - ordered: true
+ aligned_by: src
+ file_type: parquet
+ - ordered: true
+ aligned_by: dst
+ file_type: parquet
+property_groups:
+ - file_type: parquet
+ properties:
+ - name: creationDate
+ data_type: string
+ is_primary: false
+version: gar/v1
+```
+
:::note
Please note that GraphAr supports the storage of multiple types of adjLists
for a given group of edges, e.g., a group of edges could be accessed in both
CSR and CSC way when two copies (one is **ordered_by_source** and the other is
**ordered_by_dest**) of the relevant data are present in GraphAr.
:::
-See also [Gar Information
Files](https://graphar.apache.org/docs/libraries/cpp/getting-started#gar-information-files)
for an example.
+For usage examples, please refer to [Information in
C++](https://graphar.apache.org/docs/libraries/cpp/getting-started/#construct-information)
and [Information in
Java](https://graphar.apache.org/docs/libraries/java/info/getting-started).
## Data files
@@ -196,4 +275,4 @@ See also [GraphAr Data
Files](https://graphar.apache.org/docs/libraries/cpp/gett
## Implementation
-The GraphAr libraries may implement part of the GraphAr format. The
implementation status of the GraphAr libraries can refer to the [GraphAr
implementation status](implementation-status.md).
+The GraphAr libraries may implement part of the GraphAr format. The
implementation status of the GraphAr libraries can refer to the [GraphAr
implementation status](implementation-status.md).
\ No newline at end of file
diff --git a/maven-projects/info/README.md b/maven-projects/info/README.md
index fb840e1c..2a469dc7 100644
--- a/maven-projects/info/README.md
+++ b/maven-projects/info/README.md
@@ -1,5 +1,61 @@
# GraphAr Info
-Module contains a lightweight set of interfaces and utils for building a
GraphAr read/write tools on top.
+The **graphar-info** module is part of the pure Java implementation of GraphAr.
+
+## Key Features
+
+The **java-info** module offers a lightweight, zero-dependencies yet powerful
solution for **GraphAr metadata management**. It is responsible for:
+
+* **Loading & Saving Metadata**: Read and write GraphAr metadata files in YAML
format.
+* **Schema Parsing**: Extract graph schema definitions (e.g., vertex/edge
types, properties).
+* **Storage Information Retrieval**: Obtain detailed storage information from
metadata, including file URIs, chunk sizes, etc.
+
+## Building
+
+To build the graphar-info module, you need:
+
+- JDK 11 or higher
+- Maven 3.5 or higher
+
+Build the module with Maven:
+
+```bash
+mvn clean install
+```
+
+## Usage
+
+Here's a simple example of how to use the graphar-info module:
+
+For more usage examples and detailed information, please refer to [Getting
Started with Info
Module](https://graphar.apache.org/docs/libraries/java/info/getting-started).
+
+```java
+import org.apache.graphar.info.GraphInfo;
+import org.apache.graphar.info.loader.GraphInfoLoader;
+import
org.apache.graphar.info.loader.impl.LocalFileSystemStreamGraphInfoLoader;
+
+// Load graph info from a YAML file
+GraphInfoLoader loader = new LocalFileSystemStreamGraphInfoLoader();
+GraphInfo graphInfo =
loader.loadGraphInfo(Paths.get("path/to/graph.yml").toUri());
+
+// Access graph metadata
+String graphName = graphInfo.getName();
+List<VertexInfo> vertices = graphInfo.getVertexInfos();
+List<EdgeInfo> edges = graphInfo.getEdgeInfos();
+
+// Access vertex metadata
+VertexInfo personVertex = vertices.get(0);
+String vertexType = personVertex.getType();
+long chunkSize = personVertex.getChunkSize();
+
+// Access edge metadata
+EdgeInfo knowsEdge = edges.get(0);
+String edgeType = knowsEdge.getEdgeType();
+boolean isDirected = knowsEdge.isDirected();
+```
+## Dependencies
+
+The graphar-info module has minimal dependencies:
+- SnakeYAML for YAML parsing (shaded in the JAR)
**Under active development**
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
