Schema Management

The GQLDB Python driver provides convenience methods for managing labels, properties, constraints, indexes, and fulltext indexes. These methods require a graph to be selected via use_graph() or a QueryConfig with graph_name.

Label Methods

Listing Labels

Python
from gqldb import GqldbClient, GqldbConfig

client.use_graph("myGraph")

# All labels
labels = client.show_labels()
for label in labels:
    print(f"{label.labels} ({label.type})")

# Node labels only
node_labels = client.show_node_labels()

# Edge labels only
edge_labels = client.show_edge_labels()

Listing Types (CLOSED Graph)

Show labels with their property definitions:

Python
# Node types with properties
node_types = client.show_node_types()
for nt in node_types:
    print(f"{nt.name}: {[p.name for p in nt.properties]}")

# Edge types with properties
edge_types = client.show_edge_types()

Getting a Single Label

Python
# Returns None if not found
person_label = client.get_node_label("Person")
if person_label:
    print(f"Found: {person_label.name}")

knows_label = client.get_edge_label("KNOWS")

Creating Labels

Create labels with property definitions (required for CLOSED graphs):

Python
from gqldb.types.convenience import ConvPropertyDef, DBType

# Create a node label with properties
client.create_node_label("Person", [
    ConvPropertyDef(name="name", type="STRING"),
    ConvPropertyDef(name="age", type="INT64"),
])

# Create an edge label
client.create_edge_label("KNOWS", [
    ConvPropertyDef(name="since", type="INT64"),
])

# Idempotent create — returns True if created, False if already existed
created = client.create_label_if_not_exist(DBType.NODE, "Person", [
    ConvPropertyDef(name="name", type="STRING"),
])

Renaming Labels

Python
client.alter_node_label("OldName", "NewName")
client.alter_edge_label("OldEdge", "NewEdge")

Dropping Labels

Python
client.drop_node_label("Person")
client.drop_edge_label("KNOWS", "LIKES")  # Multiple names

Property Methods

Managing Properties

Python
# Show properties for a label
props = client.show_node_property("Person")
for p in props:
    print(f"  {p.name}: {p.type}")

# Get a single property (returns None if not found)
prop = client.get_node_property("Person", "name")

# Add properties
client.create_node_property("Person", [
    ConvPropertyDef(name="email", type="STRING"),
])

# Idempotent add — returns True if created
created = client.create_property_if_not_exist(DBType.NODE, "Person", [
    ConvPropertyDef(name="email", type="STRING"),
])

# Drop properties
client.drop_node_property("Person", "email")
client.drop_edge_property("KNOWS", "weight", "note")  # Multiple names

Constraint Methods

Managing Constraints (CLOSED Graph)

Python
from gqldb.types.convenience import DBType

# NOT NULL
client.create_not_null_constraint(DBType.NODE, "Person", "name")
client.drop_not_null_constraint(DBType.NODE, "Person", "name")

# UNIQUE
client.create_unique_constraint(DBType.NODE, "Person", "email")
client.drop_unique_constraint(DBType.NODE, "Person", "email")

Index Methods

Managing Indexes

Python
from gqldb.types.convenience import IndexProperty

client.use_graph("myGraph")

# Show indexes
indexes = client.show_index()
for idx in indexes:
    print(f"{idx.index_name} on {idx.label}.{idx.property} ({idx.status})")

# Create index
client.create_node_index("idx_name", "Person", [IndexProperty(name="name")])

# Create index with prefix length (for string properties)
client.create_node_index("idx_prefix", "Person", [IndexProperty(name="name", prefix_length=10)])

client.create_edge_index("idx_since", "KNOWS", [IndexProperty(name="since")])

# Drop index
client.drop_node_index("idx_name")
client.drop_edge_index("idx_since")

Fulltext Index Methods

Managing Fulltext Indexes

Python
client.use_graph("myGraph")

# Show fulltext indexes
fts = client.show_fulltext()
for ft in fts:
    print(f"{ft.index_name} on {ft.schema_name} ({ft.status})")

# Create fulltext index
client.create_node_fulltext("ft_name", "Person", ["name"])
client.create_edge_fulltext("ft_note", "KNOWS", ["note"])

# Drop fulltext index
client.drop_node_fulltext("ft_name")
client.drop_edge_fulltext("ft_note")

Per-call Configuration

All schema management methods accept an optional QueryConfig for per-call graph targeting:

Python
from gqldb.client import QueryConfig

config = QueryConfig(graph_name="graphA")

# Target a specific graph without use_graph()
labels = client.show_node_labels(config=config)
client.create_node_label("User", props, config=config)
client.create_node_index("idx_name", "User", index_props, config=config)

Special Character Handling

Label and property names containing special characters (spaces, hyphens, dots) are automatically wrapped in backticks:

Python
# These work with special characters
client.create_node_label("My Label", [...])        # → `My Label`
client.create_node_property("my-label", [...])     # → `my-label`
client.alter_node_label("my.old", "my.new")        # → `my.old` → `my.new`

NOTE

Note: Graph names, index names, and fulltext index names do not support special characters — only letters, digits, and underscores are allowed.

Complete Example

Python
from gqldb import GqldbClient, GqldbConfig
from gqldb.types.convenience import ConvPropertyDef, DBType, IndexProperty
from gqldb.errors import GqldbError

def main():
    config = GqldbConfig(hosts=["localhost:9000"], timeout=30)

    with GqldbClient(config) as client:
        client.login("admin", "password")

        # Create a closed graph for schema management
        client.create_closed_graph("schemaDemo")
        client.use_graph("schemaDemo")

        # Create node labels with properties
        print("=== Creating Labels ===")
        client.create_node_label("Person", [
            ConvPropertyDef(name="name", type="STRING"),
            ConvPropertyDef(name="age", type="INT64"),
            ConvPropertyDef(name="email", type="STRING"),
        ])
        client.create_edge_label("KNOWS", [
            ConvPropertyDef(name="since", type="INT64"),
        ])
        print("Labels created")

        # Add constraints
        print("\n=== Adding Constraints ===")
        client.create_not_null_constraint(DBType.NODE, "Person", "name")
        client.create_unique_constraint(DBType.NODE, "Person", "email")
        print("Constraints added")

        # Create indexes
        print("\n=== Creating Indexes ===")
        client.create_node_index("idx_person_name", "Person", [IndexProperty(name="name")])
        client.create_node_fulltext("ft_person_name", "Person", ["name"])
        print("Indexes created")

        # Show schema
        print("\n=== Node Types ===")
        for nt in client.show_node_types():
            prop_names = [p.name for p in nt.properties]
            print(f"  {nt.name}: {', '.join(prop_names)}")

        print("\n=== Indexes ===")
        for idx in client.show_index():
            print(f"  {idx.index_name} on {idx.label}.{idx.property}")

        print("\n=== Fulltext Indexes ===")
        for ft in client.show_fulltext():
            print(f"  {ft.index_name} on {ft.schema_name}")

        # Add a property later
        print("\n=== Adding Property ===")
        client.create_node_property("Person", [
            ConvPropertyDef(name="phone", type="STRING"),
        ])

        # Verify
        person_props = client.show_node_property("Person")
        print(f"Person properties: {[p.name for p in person_props]}")

        # Clean up
        client.drop_graph("schemaDemo")
        print("\nDone")

if __name__ == "__main__":
    main()