Metadata-Version: 2.4
Name: millenniumdb_driver
Version: 1.2.1
Summary: The official MillenniumDB driver for Python
Author-email: Vicente Calisto <vecalisto@uc.cl>, Matías Maldonado <matiasmaldonado@uc.cl>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MillenniumDB/MillenniumDB-driver-python
Project-URL: Bug Tracker, https://github.com/MillenniumDB/MillenniumDB-driver-python/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: websocket-client
Dynamic: license-file


# MillenniumDB Driver

---

[![PyPI Latest Release](https://img.shields.io/pypi/v/millenniumdb-driver.svg)](https://pypi.org/project/millenniumdb-driver/) [![PyPI downloads](https://img.shields.io/pypi/dm/millenniumdb-driver.svg?label=pypi%20downloads)](
https://pypi.org/project/millenniumdb-driver/)
![License](https://img.shields.io/pypi/l/millenniumdb-driver)

Here you can find the official Python driver for the [MillenniumDB server](https://github.com/MillenniumDB/MillenniumDB).

Check out the driver for different languages!

- [MillenniumDB driver in JavaScript](https://github.com/MillenniumDB/MillenniumDB-driver-javascript)

## Table of contents

1. [Directory structure](#1-directory-structure)
2. [Build instructions](#2-build-instructions)

## 1. Directory structure

```txt
📦millenniumdb_driver
├── 📂docs/ ---------------------------- Documentation generator (Sphinx)
├── 📂src/ ----------------------------- The Python implementation
├── 📜LICENSE
├── 📜README.md
├── 📜pyproject.toml
└── 📜setup.cfg
```

## 2. Build instructions

### Setup

Dependencies:

- Git
- Setuptools
- Wheel
- A running MillenniumDB server instance

### Installation

Install the driver and the dependecies.

```bash
pip install millenniumdb_driver
```

### Usage

After successfully installing the project, you can start using the library in your Python programs.

#### Creating a Driver instance

First you must create a `Driver` instance:

```python
import millenniumdb_driver

url = 'your-server-url' # e.g. ws://localhost:1234
driver = millenniumdb_driver.driver(url)
```

When you are done with the driver, you should close it before exiting the application.

```python
driver.close()
```

#### Acquiring a Session

For sending queries to the MillenniumDB server, you must acquire a session instance:

```python
session = driver.session()
```

Then you can send queries through your session.

```python
query = 'MATCH (?from)-[:?type]->(?to) RETURN * LIMIT 10'
result = session.run(query)
```

#### Consuming results

The alternatives for consuming results must never be mixed because it would generate undefined behavior on your client and/or server. It is important to mention that the session must be closed when your operations are done.

```python
result.variables() -> Tuple[str]
```

Returns the list of variables in the result.

```python
result.records() -> List[Record]
```

Returns the list of `Records` in the result.

```python
result.values() -> List[object]
```

Returns the list of values in the result.

```python
result.data() -> List[Dict[str, object]]
```

Returns the list of records in the result as dictionaries.

```python
result.to_df() -> "DataFrame"
```

Returns the result as a Pandas DataFrame.

```python
result.summary() -> object
```

Returns the summary of the result.

```python
for record in result: -> Iterator[Record]
    print(record)
```

Iterates over each record in result.

### Parametric queries

To prevent injections, `session.run()` accepts a second argument: a dictionary that maps variables to values. This lets you create safe, parametric queries with preset bindings that are automatically sanitized by the database.

```python
result = session.run(
    "MATCH (?person :Person)-[:owns]->(?car :Car) WHERE ?person.age > ?my_arg RETURN *",
    { "my_arg": 25 },
)
```

MillenniumDB types can be constructed from python to pass it as parametric values. This are available under `millenniumdb_driver.graph_objects` module. For example:

```python
import millenniumdb_driver as mdb

my_iri = mdb.graph_objects.IRI("http://example.com")

# now you can use this IRI as a value
```
