# Raw queries

Source: https://docs.rushdb.com/learn/records-and-queries/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,sql` |

The statement runs in the RushDB engine, which implements a documented [openCypher profile](../../engine/languages/cypher.md): `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()`

```python
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'}, ...]
```

**TypeScript**

`db.query.raw()`

```typescript
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`

```bash
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 }
  }'
```

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

---

## Real-world example

Find people employed by a company and return selected fields:

**Python**

```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"])
```

**TypeScript**

```typescript
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**

```bash
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](../../connect/sql-and-cypher.mdx) and [Query languages](../../engine/languages/README.md) in the engine manual.

---

## See also

- [Find & Query](./find-and-query.mdx) — SearchQuery API (recommended for most use cases)
- [Connect Records](../relationships/connect-records.mdx) — relationship traversal via SearchQuery
- [openCypher in the engine manual](../../engine/languages/cypher.md) — supported statements, parameters and known gaps
