Torque API Reference

Torque is CogDB's graph traversal language implemented as a Python API.

Graph

Graph(graph_name, cog_home="cog_home", cog_path_prefix=None, enable_caching=True, flush_interval=1)

Creates a Graph object. Parameters:

cog_home - Home directory name
cog_path_prefix - Parent directory
enable_caching - Enable caching (default: True)
flush_interval - Controls write flushing (default: 1)

flush_interval Options

Value	Behavior	Use Case
`1`	Flush every write	Interactive use
`> 1`	Async flush every N writes	Bulk inserts
`0`	Manual flush via `sync()`	Maximum speed

Examples:

from cog.torque import Graph

g = Graph("my_graph")

# Custom location
g = Graph("my_graph", cog_home="data", cog_path_prefix="/var/lib")

# For bulk inserts set flush interval to higher value, default is 0, which would flush on every write.
g = Graph("my_graph", flush_interval=1000)

Understanding Traversal State

Each traversal method moves the cursor. The v() method resets the cursor.

g.v("alice").out("knows").all()   # {'result': [{'id': 'bob'}]}
g.v("bob").out("likes").all()     # {'result': [{'id': 'tacos'}]}

Terminal methods (all(), count()) do NOT reset the traversal. Only v() resets the cursor.

put

put(vertex1, predicate, vertex2, update=False, create_new_edge=False)

Adds an edge connecting two vertices.

Prop

Type

Examples:

g.put("alice", "follows", "bob")
g.put("bob", "status", "cool_person")

put_batch

put_batch(triples)

Adds multiple edges at once. Faster than repeated put() calls.

Prop

Type

Example:

g.put_batch([
    ("alice", "follows", "bob"),
    ("bob", "follows", "charlie"),
    ("charlie", "follows", "alice"),
    ("alice", "status", "active")
])

sync

sync()

Force pending writes to disk.

Example:

g = Graph("my_graph", flush_interval=0)
for i in range(10000):
    g.put(f"node_{i}", "connects", f"node_{i+1}")
g.sync()  # Flush all pending writes

drop

drop(vertex1, predicate, vertex2)

Removes an edge.

Prop

Type

Example:

g.drop("alice", "follows", "bob")

v

v(vertex=None)

Start traversal at a vertex. If no vertex is given, traversal starts from all vertices.

Prop

Type

Examples:

# Start from a specific vertex
g.v("alice").out("follows").all()

# Start from multiple vertices
g.v(["alice", "bob"]).out("follows").all()

# Start from all vertices
g.v().out("follows").all()

out

out(predicates=None)

Traverse forward through outgoing edges.

Prop

Type

Examples:

# Traverse all outgoing edges
g.v("bob").out().all()

# Traverse a specific edge type
g.v("bob").out("follows").all()

# Multiple edge types
g.v("bob").out(["follows", "status"]).all()

inc

inc(predicates=None)

Traverse backward through incoming edges.

Prop

Type

Examples:

# Find all vertices that follow "bob"
g.v("bob").inc("follows").all()

# Multiple edge types
g.v("cool_person").inc(["status"]).all()

both

both(predicates=None)

Traverse in both directions (combines out() and inc()).

Prop

Type

Examples:

# Find all connections (in either direction)
g.v("alice").both("knows").all()

# Multiple predicates
g.v("alice").both(["knows", "works_with"]).all()

bfs

bfs(predicates=None, max_depth=None, min_depth=0, direction="out", until=None, unique=True)

Breadth-first search traversal.

Parameter	Description	Default
`predicates`	Edge types to follow	None
`max_depth`	Maximum depth	None
`min_depth`	Minimum depth	0
`direction`	"out", "inc", or "both"	"out"
`until`	Stop condition lambda	None
`unique`	Visit each vertex once	True

Examples:

# Find all vertices within 2 hops
g.v("alice").bfs(predicates="follows", max_depth=2).all()

# Find vertices at exactly depth 2-3
g.v("alice").bfs(max_depth=3, min_depth=2).all()

# Stop when target is found
g.v("alice").bfs(until=lambda v: v == "target_user").all()

dfs

dfs(predicates=None, max_depth=None, min_depth=0, direction="out", until=None, unique=True)

Depth-first search traversal. Same parameters as bfs().

Examples:

g.v("alice").dfs(predicates="follows", max_depth=5).all()
g.v("target").dfs(direction="inc", max_depth=3).all()

is_

is_(*nodes)

Filter to specific vertices.

Prop

Type

Examples:

g.v("alice").out("follows").is_("bob").all()
g.v("alice").out("follows").is_("bob", "charlie").all()

unique

unique()

Remove duplicate vertices.

Example:

g.v(["alice", "bob"]).out("follows").unique().all()

limit

limit(n)

Limit to first n vertices.

Prop

Type

Example:

g.v("alice").out("follows").limit(5).all()

skip

skip(n)

Skip first n vertices.

Prop

Type

Example:

# Pagination: skip first 10, take next 10
g.v().out("follows").skip(10).limit(10).all()

back

back(tag)

Navigate to a previously tagged position.

Prop

Type

Example:

g.v("alice").tag("start").out("follows").out("likes").back("start").all()

filter

filter(func)

Filter vertices using a lambda.

Prop

Type

Examples:

g.v().filter(lambda v: "user" in v).all()
g.v().filter(lambda v: v.isdigit() and int(v) > 100).all()

scan

scan(limit=10, scan_type='v')

Scan nodes ('v') or edges ('e').

Prop

Type

Examples:

g.scan(10, 'v')  # Scan first 10 vertices
g.scan(5, 'e')   # Scan first 5 edges

tag

tag(tag_names)

Capture vertex IDs at this point. Used by view().

Prop

Type

Examples:

g.v("bob").out().tag("friend").all()
g.v("bob").tag("start").out("follows").tag("middle").out().tag("end").all()

view

view(view_name, js_src="...")

Create HTML visualization. Saves to {cog_home}/views/{view_name}.html.

Prop

Type

Example:

view = g.v("bob").out().tag("from").inc().tag("to").view("bob_network")
print(view.url)

render

render(height=700, width=700)

Display visualization in Jupyter notebooks.

Prop

Type

Examples:

g.v("alice").out("follows").tag("friend").view("alice_friends").render()
g.v("alice").out("follows").view("large_view").render(height=800, width=1200)

has

has(predicates, vertex)

Filter vertices with matching outgoing edges.

Prop

Type

Examples:

g.v().has("follows", "fred").all()
g.v().has("status", "cool_person").all()

count

count()

Count vertices. Terminal function.

Examples:

g.v("alice").out("follows").count()  # → 3
g.v().out("status").count()          # → 5

all

all(options=None)

Return all vertices.

Prop

Type

Examples:

g.v("bob").out().all()
# → {'result': [{'id': 'fred'}, {'id': 'cool_person'}]}

g.v("bob").out().all('e')  # Include edges
# → {'result': [{'id': 'fred', 'edges': ['follows']}]}

lsv

lsv()

List saved view names.

getv

getv(view_name)

Load a saved view.

Prop

Type

Example:

view = g.getv("bob_network")
view.render()

load_csv

load_csv(csv_path, id_column_name, graph_name=None)

Load a CSV file into the graph.

Prop

Type

Examples:

# Load CSV with "user_id" as the identifier
g.load_csv("/path/to/users.csv", "user_id")

# Load into a specific graph name
g.load_csv("/path/to/users.csv", "user_id", "user_graph")

load_triples

load_triples(graph_data_path, graph_name=None)

Load triples from a file (N-Triples or N-Quads).

Prop

Type

Examples:

g.load_triples("/path/to/data.nq")
g.load_triples("/path/to/data.nq", "social_graph")

load_edgelist

load_edgelist(edgelist_path, graph_name=None)

Load an edge list file into the graph.

Prop

Type

Example:

g.load_edgelist("/path/to/edges.txt")

Embedding Methods

CogDB supports storing and querying word/vertex embeddings for similarity search.

put_embedding

put_embedding(word, embedding)

Store an embedding vector for a word/vertex.

Prop

Type

Example:

g.put_embedding("machine_learning", [0.1, 0.2, 0.3, ...])

put_embeddings_batch

put_embeddings_batch(word_embedding_pairs)

Bulk insert multiple embeddings efficiently.

Prop

Type

Example:

g.put_embeddings_batch([
    ("apple", [0.1, 0.2, 0.3]),
    ("orange", [0.2, 0.3, 0.4]),
    ("banana", [0.15, 0.25, 0.35])
])

get_embedding

get_embedding(word)

Retrieve an embedding vector.

Prop

Type

Example:

embedding = g.get_embedding("machine_learning")
# → [0.1, 0.2, 0.3, ...]

delete_embedding

delete_embedding(word)

Remove an embedding.

Prop

Type

Example:

g.delete_embedding("outdated_term")

sim

sim(word, operator, threshold, strict=False)

Filter vertices by cosine similarity to a word.

Parameter	Description
`word`	Word to compare against
`operator`	`"="`, `">"`, `"<"`, `">="`, `"<="`, or `"in"`
`threshold`	Float value, or list of 2 floats for `"in"` operator
`strict`	If `True`, raise error for missing embeddings

Examples:

# Find vertices with similarity > 0.8
g.v().sim("machine_learning", ">", 0.8).all()

# Find vertices with similarity in range
g.v().sim("machine_learning", "in", [0.5, 0.9]).all()

k_nearest

k_nearest(word, k=10)

Find the k vertices most similar to the given word.

Prop

Type

Example:

g.v().k_nearest("machine_learning", k=5).all()

Network Methods

serve

serve(port=8080, host="0.0.0.0", blocking=False, writable=False, share=False)

Start HTTP server for this graph instance.

Examples:

# Basic server
g.serve(port=8080)

# Allow write operations
g.serve(port=8080, writable=True)

# Share publicly via CogDB relay
g.serve(port=8080, share=True)
print(g.share_url())  # https://abc123.s.cogdb.io/

stop

stop()

Stop serving this graph.

Example:

g.stop()

connect (class method)

Graph.connect(url, timeout=30)

Connect to a remote CogDB server.

Prop

Type

Example:

remote = Graph.connect("http://192.168.1.5:8080/social")
remote.v("alice").out("knows").all()

Complete Example

Example:

from cog.torque import Graph, ASC, DESC

# Create graph
g = Graph("social_network")

# Add data
g.put_batch([
    ("alice", "follows", "bob"),
    ("bob", "follows", "charlie"),
    ("charlie", "follows", "alice"),
    ("alice", "status", "active"),
    ("bob", "status", "active"),
    ("charlie", "status", "inactive")
])

# Query: Find who alice follows
g.v("alice").out("follows").all()
# → {'result': [{'id': 'bob'}]}

# Query: Find followers of bob, ordered
g.v("bob").inc("follows").order(ASC).all()
# → {'result': [{'id': 'alice'}]}

# Query: Complex traversal with tags
g.v("alice").tag("start").out("follows").tag("middle").out("follows").tag("end").all()
# → {'result': [{'start': 'alice', 'middle': 'bob', 'end': 'charlie', 'id': 'charlie'}]}

# Query: Find active users
g.v().has("status", "active").all()
# → {'result': [{'id': 'alice'}, {'id': 'bob'}]}

# Create visualization
g.v("alice").out().tag("friend").view("alice_network")

# Close when done
g.close()

Torque API Reference

On this page