Quick Start

Using Diamond

Diamond can be integrated into your workflows to compress and manage Labeled Property Graphs. The core component for this is the PropertyGraph class.

To use Diamond, you'll typically import PropertyGraph and use its methods to read your existing graph data and write it out in the compressed .diamond format, or convert it to other supported formats.

Example: Compressing a PG_JSONL file to .diamond

from pathlib import Path
from diamond_graph import PropertyGraph

input_path = Path("./data/my_graph.jsonl")
output_path = Path("./data/my_graph.diamond")

# Read from a PG_JSONL file
try:
    pg = PropertyGraph.read_pg_jsonl(input_path)
    print(f"Successfully read {input_path}")

    # Write to a .diamond file
    pg.write_diamond(output_path)
    print(f"Successfully wrote {output_path}")

except Exception as e:
    print(f"An error occurred: {e}")

In-Memory Representations

The PropertyGraph object also allows you to work with in-memory representations of your graph data. This is particularly useful for direct inspection or manipulation within your environment.

Key methods include:

pg.to_pg_json() -> PgJsonPropertyGraph: Converts the graph into an in-memory PG-JSON model. This representation, is ideal for examining the graph's structure and properties.
pg.to_diamond() -> DiamondGraph: Transforms the PropertyGraph into an in-memory DiamondGraph object. This format typically stores graph data using Polars DataFrames, offering efficient data manipulation capabilities.
PropertyGraph.from_diamond(diamond_graph: DiamondGraph) -> PropertyGraph: Reconstructs a PropertyGraph instance from an in-memory DiamondGraph object.

Example: Inspecting Graph Data via PG-JSON

Here's a more comprehensive example that ties together reading a graph, converting it to its PG-JSON representation, and then printing and inspecting this in-memory object.

from pathlib import Path
from diamond_graph import PropertyGraph

# Define the path to your input graph file
input_file_path = Path("./data/my_graph.jsonl")

try:
    # 1. Read the graph from a file
    original_graph = PropertyGraph.read_pg_jsonl(input_file_path)
    print(f"Successfully read graph from {input_file_path}")

    # 2. Convert to in-memory PG-JSON representation
    pg = original_graph.to_pg_json() # pg now holds the PgJsonPropertyGraph object

    # 3. Print the entire PG-JSON object
    # Note: For very large graphs, this will produce extensive output.
    # It's often more practical to inspect specific parts as shown below.
    print("\n--- Full PG-JSON Representation (can be verbose) ---")
    print(pg)

    # 4. Inspecting specific parts of the PG-JSON data
    print("\n--- Inspecting Graph Details ---")
    print(f"The graph has {len(pg.nodes)} nodes.")
    print(f"The graph has {len(pg.edges)} edges.")

    if pg.nodes:
        print(f"First node ID: {pg.nodes[0].id}, Labels: {pg.nodes[0].labels}, Properties: {pg.nodes[0].properties}")

    if pg.edges:
        first_edge = pg.edges[0]
        print(f"First edge - ID: {first_edge.id}")
        print(f"  Source Node ID: {first_edge.source}, Target Node ID: {first_edge.to}")
        print(f"  Labels: {first_edge.labels}, Properties: {first_edge.properties}")
    else:
        print("The graph has no edges to inspect.")

except FileNotFoundError:
    print(f"Error: The file {input_file_path} was not found. Please ensure the path is correct.")
except Exception as e:
    print(f"An error occurred: {e}")

Using Diamond

Basic Operations

Example: Compressing a PG_JSONL file to .diamond

In-Memory Representations

Example: Inspecting Graph Data via PG-JSON

On this page