Raw Queries

db.query.raw() runs an openCypher statement against your graph. Use it for the advanced cases where the SearchQuery API is not expressive enough; SearchQuery remains the recommended way to read data.

	RushDB Cloud	Self-hosted engine (direct mode)
query.raw with openCypher	✓	✓ when the engine runs with --languages cypher

The statement runs in the RushDB engine, which implements a documented openCypher profile: MATCH, WHERE, RETURN, WITH, aggregation, OPTIONAL MATCH, UNION, CREATE, SET, DELETE and more. Check that page for what is not supported before relying on a construct.

Each row comes back as an object keyed by the statement's RETURN columns, in data.records.

---

Basic Usage

Python

db.query.raw()

from rushdb import RushDB

db = RushDB("RUSHDB_API_KEY")

result = db.query.raw({
    "query": "MATCH (n:Person) RETURN n.name AS name LIMIT $limit",
    "params": {"limit": 10}
})

print(result["data"]["records"])  # [{'name': 'Ada'}, ...]

TSTypeScript

db.query.raw()

const result = await db.query.raw({
  query: 'MATCH (n:Person) RETURN n.name AS name LIMIT $limit',
  params: { limit: 10 }
})

console.log(result.data.records) // [{ name: 'Ada' }, ...]

shell

POST /api/v1/query/raw

curl -X POST https://api.rushdb.com/api/v1/query/raw \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{
    "query": "MATCH (n:Person) RETURN n.name AS name LIMIT $limit",
    "params": { "limit": 10 }
  }'

{ "data": { "records": [{ "name": "Ada" }] }, "success": true }

---

Real-World Example

Find people employed by a company and return selected fields:

Python

company = "Acme Corp"
result = db.query.raw({
    "query": """
        MATCH (c:Company { name: $company })-[:EMPLOYS]->(p:Person)
        RETURN p.name AS name, p.email AS email, c.name AS company
        ORDER BY name
        LIMIT $limit
    """,
    "params": {"company": company, "limit": 50}
})

for row in result["data"]["records"]:
    print(row["name"], row["email"])

TSTypeScript

const company = 'Acme Corp'
const result = await db.query.raw({
  query: `
    MATCH (c:Company { name: $company })-[:EMPLOYS]->(p:Person)
    RETURN p.name AS name, p.email AS email, c.name AS company
    ORDER BY name
    LIMIT $limit
  `,
  params: { company, limit: 50 }
})

console.log(result.data.records)

shell

curl -X POST https://api.rushdb.com/api/v1/query/raw \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -d '{
    "query": "MATCH (c:Company { name: $company })-[:EMPLOYS]->(p:Person) RETURN p.name AS name, p.email AS email, c.name AS company ORDER BY name LIMIT $limit",
    "params": { "company": "Acme Corp", "limit": 50 }
  }'

---

Other query languages

A self-hosted engine also accepts SQL, ISO GQL, Gremlin, SQL/PGQ and Mongo-style statements over its native protocol, and SQL over the PostgreSQL wire protocol. See SQL and Cypher clients and Query languages in the engine manual.

---

See also

• Find & Query — SearchQuery API (recommended for most use cases)
• Connect Records — relationship traversal via SearchQuery
• openCypher in the engine manual — supported statements, parameters and known gaps