# xwquery

**Company:** eXonware.com  
**Author:** eXonware Backend Team  
**Email:** connect@exonware.com  

Query and transform in-memory data with one API: SQL-style scripts, graph patterns, aggregations, and 35+ alternate surface syntaxes (Cypher, GraphQL, JMESPath, and others). Built to pair with xwnode, xwdata, and xwentity in the eXonware stack.

## Install

```bash
pip install exonware-xwquery
```

## Basic usage

```python
from exonware.xwquery import XWQuery

data = {'users': [
    {'name': 'Alice', 'age': 30, 'city': 'NYC'},
    {'name': 'Bob', 'age': 25, 'city': 'LA'},
    {'name': 'Charlie', 'age': 35, 'city': 'NYC'}
]}

result = XWQuery.execute("""
    SELECT name, age
    FROM users
    WHERE age > 25 AND city = 'NYC'
""", data)

print(result)
# [{'name': 'Alice', 'age': 30}, {'name': 'Charlie', 'age': 35}]
```

## What you get

- **Broad operation set** - Core CRUD (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP), filtering (WHERE, FILTER, LIKE, IN, RANGE, …), aggregation (GROUP BY, HAVING, SUM, COUNT, …), graph helpers (MATCH, PATH, …), and advanced pieces (JOIN, UNION, WITH, WINDOW, PIPE, …).
- **Many input languages** - Strategies for SQL-family dialects, Cypher/Gremlin/SPARQL/GraphQL, document and log query languages (MQL, Elasticsearch DSL, PromQL, Flux, …), and more. Parse or convert between them where supported.
- **Structure-aware execution** - The engine can adapt work to linear, tree, graph, or hybrid shapes when the backend exposes that metadata.

```python
linear_data = [1, 2, 3, 4, 5]
tree_data = {'a': 1, 'b': 2, 'c': 3}
graph_data = {'nodes': [...], 'edges': [...]}

XWQuery.execute("SELECT * WHERE value > 2", linear_data)
XWQuery.execute("SELECT * WHERE key BETWEEN 'a' AND 'c'", tree_data)
XWQuery.execute("MATCH (n)-[r]->(m)", graph_data)
```

## Script examples

```xquery
SELECT name, email, age FROM users WHERE age >= 18;

SELECT department, COUNT(*) AS employee_count, AVG(salary) AS avg_salary
FROM employees
GROUP BY department
HAVING avg_salary > 50000;

MATCH (u:User)-[:FRIENDS_WITH]->(f:User)
WHERE u.age > 25
RETURN u.name, f.name;
```

## Format conversion

```python
sql_query = "SELECT id, name FROM users WHERE age > 25"
graphql = XWQuery.convert(sql_query, from_format='sql', to_format='graphql')

cypher_query = "MATCH (u:User)-[:WORKS_AT]->(c:Company) RETURN u.name, c.name"
sql = XWQuery.convert(cypher_query, from_format='cypher', to_format='sql')

any_query = XWQuery.parse(query_string)
target_format = any_query.to_format('mongodb')
```

## Stack integration

**xwnode**

```python
from exonware.xwnode import XWNode
from exonware.xwquery import XWQuery

node = XWNode.from_native({'users': [...]})
result = XWQuery.execute("SELECT * FROM users WHERE active = true", node)
```

**xwdata**

```python
from exonware.xwdata import XWData
from exonware.xwquery import XWQuery

data = XWData.load('users.json')
filtered = XWQuery.execute("SELECT * WHERE age > 18", data)
filtered.save('adults.xml')
```

**xwentity**

```python
from exonware.xwentity import XWEntity
from exonware.xwquery import XWQuery

class User(XWEntity):
    name: str
    age: int
    email: str

users = XWQuery.execute("SELECT * FROM User WHERE age > 18")
```

## Docs

- [docs/INDEX.md](docs/INDEX.md) - full map  
- [docs/GUIDE_01_USAGE.md](docs/GUIDE_01_USAGE.md) - usage  
- [docs/REF_15_API.md](docs/REF_15_API.md) - API  
- [docs/REF_13_ARCH.md](docs/REF_13_ARCH.md) - architecture  
- [docs/PROJECT_PHASES.md](docs/PROJECT_PHASES.md) - phases and roadmap  
- [docs/REF_51_TEST.md](docs/REF_51_TEST.md) - tests  

## Development

```bash
pip install -e .
python tests/runner.py
python tests/runner.py --core
python tests/runner.py --unit
python tests/runner.py --integration
```

## License

MIT - see [LICENSE](LICENSE).

## Ecosystem

- [xwsystem](https://github.com/exonware/xwsystem)  
- [xwnode](https://github.com/exonware/xwnode)  
- [xwquery](https://github.com/exonware/xwquery) (this repo)  
- [xwdata](https://github.com/exonware/xwdata)  
- [xwschema](https://github.com/exonware/xwschema)  
- [xwaction](https://github.com/exonware/xwaction)  
- [xwentity](https://github.com/exonware/xwentity)  
- [xwstorage](https://github.com/exonware/xwstorage)  
- [xwbase](https://github.com/exonware/xwbase)  
Version: 0.9.0.6 | Updated: 30-Mar-2026

*Built with ❤️ by eXonware.com - Revolutionizing Python Development Since 2025*
