Metadata-Version: 2.4
Name: arcadedb
Version: 26.11.1
Summary: ArcadeDB embedded multi-model database, native build: the engine as a GraalVM native-image library, no JVM, no JPype. For heavy long-running loads use the JVM build, arcadedb-jvm; both import as arcadedb
Author-email: Taewoon Kim <taewoon@humem.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/ArcadeData/arcadedb-python
Project-URL: Repository, https://github.com/ArcadeData/arcadedb-python
Project-URL: Bug Tracker, https://github.com/ArcadeData/arcadedb-python/issues
Project-URL: ArcadeDB Upstream, https://github.com/ArcadeData/arcadedb
Keywords: database,graph,document,multi-model,arcadedb,embedded,native-image,graalvm,native
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Database
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
License-File: licenses/Apache-2.0.txt
License-File: licenses/GraalVM-CE-LICENSE.txt
License-File: licenses/GraalVM-THIRD_PARTY_LICENSE.txt
License-File: licenses/GraalVM-native-image-LICENSE.txt
Provides-Extra: numpy
Requires-Dist: numpy>=1.26.4; extra == "numpy"
Provides-Extra: arrow
Requires-Dist: pyarrow>=23.0.1; extra == "arrow"
Requires-Dist: numpy>=1.26.4; extra == "arrow"
Provides-Extra: pandas
Requires-Dist: pandas>=2.2.0; extra == "pandas"
Requires-Dist: numpy>=1.26.4; extra == "pandas"
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == "polars"
Requires-Dist: pyarrow>=23.0.1; extra == "polars"
Requires-Dist: numpy>=1.26.4; extra == "polars"
Dynamic: license-file

# arcadedb (native build)

This is `arcadedb`, the native build of the ArcadeDB Python bindings, and the default choice for scripts, notebooks, tests, CLIs, serverless functions and agents. Its sibling `arcadedb-jvm` runs the Java engine on a bundled JVM: use `arcadedb-jvm` for heavy, long-running loads, where the JIT compiler makes the engine faster over time, and when you need the Java-object APIs. Both packages `import arcadedb` and have the same public API. Install one, not both. [Which package?](https://github.com/ArcadeData/arcadedb-python/blob/main/docs/modules/ROOT/pages/which-package.adoc)

ArcadeDB (SQL, openCypher, document, graph, vector, time series) runs in your Python process **without a JVM and without JPype**. The engine is compiled ahead of time with GraalVM Community Edition into a shared library (`libarcadedb.so`, `.dylib` or `.dll`), and Python loads it with `ctypes`. It starts in milliseconds and has a small memory footprint.

<!-- REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -->
> Transition note: the first release of this layout is 26.11.1. Until `arcadedb` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Install those with `uv add --prerelease allow arcadedb`. Report problems at <https://github.com/ArcadeData/arcadedb-python/issues> and say that you use the native build.

## Install

```bash
uv add arcadedb
```

Optional extras for the columnar helpers: `[numpy]`, `[arrow]`, `[pandas]`, `[polars]`.

<!-- REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -->
Old names: this package was formerly `arcadedb-embedded-native`, imported as `arcadedb_native`. The old project is archived on PyPI: it gets no new releases and no shim. A last release of the JVM project `arcadedb-embedded` will install this package.

If `arcadedb-jvm` is installed in the same environment, `import arcadedb` raises an `ImportError` that names both packages. Run `uv remove arcadedb arcadedb-jvm`, then install the one you want.

## Use

```python
import arcadedb

print(arcadedb.__backend__)   # "native"

with arcadedb.create_database("/tmp/demo") as db:
    db.schema.create_vertex_type("Person")
    with db.transaction():
        db.command("sql", "CREATE VERTEX Person SET name = ?", "Ada")
    print(db.query("sql", "SELECT FROM Person").to_list())
```

`arcadedb.__backend__` is `native` for this package and `jvm` for `arcadedb-jvm`. `arcadedb.__version__` is the package version.

## What is in the wheel

- The shared library with the ArcadeDB engine: SQL and openCypher, the document, graph, key/value, vector and time series models, ACID transactions, and the in-process server with its HTTP API and the Postgres, Redis and Bolt wire protocols.
- The Python API on top of it, loaded with `ctypes`.
- Not in the image: gRPC, the MongoDB wire protocol, Raft/HA and Gremlin.
- No polyglot scripting languages (`js` or `python` as query languages, script triggers, polyglot functions). The polyglot engine is switched off at start-up (`arcadedb.polyglotEngineEnabled=false`), so the first database open writes nothing at WARNING.

## Platforms

CPython 3.11 to 3.15. One wheel per platform serves every Python version, because the library is loaded with `ctypes` and is not compiled against CPython. The images are built for the baseline CPU of the platform (`-march=compatibility`), so they do not need a special instruction set. On 3.15 the CI runs a subset of the tests, because jpype1 and ladybug, two dependencies of the full test suite, have no 3.15 wheel yet.

| Platform | Wheel tag | Note |
| --- | --- | --- |
| Linux x86-64, glibc 2.28+ | `manylinux_2_28_x86_64` | RHEL 8 and Rocky 8, Debian 10, Ubuntu 20.04 and newer |
| Linux arm64, glibc 2.28+ | `manylinux_2_28_aarch64` | |
| macOS arm64 | `macosx_<minos>_arm64` | |
| Windows x64 | `win_amd64` | The newest wheel. It is built in CI, and its test run is the least proven of the four |

Intel macOS, Windows arm64 and musl-based Linux (Alpine) are not built and not supported. On an Intel Mac use Docker or a Linux virtual machine; on Alpine use a glibc image such as `python:3.12-slim`.

## Not available or not yet

- **JVM-only APIs do not exist**: `get_java_database()` and the other `get_java_*` calls, `start_jvm()`, `jvm_kwargs` and JVM options. There is no JVM. Use `arcadedb-jvm` if you need them.
- **A few API calls raise `NotOnNativeYet`** (a `NotImplementedError`) instead of misbehaving: `AsyncExecutor.transaction`, `find_nearest_approximate` over product quantization, `get_metadata` of a foreign index, and `get_stats`.
- Free-threaded Python (3.14t) runs a subset of the tests in CI; it is informational and does not gate a release.

The bindings' own tests run against the installed wheel (the parity run). What does not pass is the list above, or JVM-only by nature.

## Licence

Apache-2.0 for ArcadeDB and these bindings. The library also contains the GraalVM Community Edition runtime and JDK class library code, licensed GPLv2 **with the Classpath Exception**, plus the Apache/BSD/MIT/UPL/EDL third-party Java libraries listed in `THIRD_PARTY_NOTICES.md`. All texts and the source locations are in the wheel's `*.dist-info/licenses/`.
