arcadedb 26.11.1.dev0__py3-none-win_amd64.whl

arcadedb/__init__.py

@@ -0,0 +1,150 @@
+"""
+ArcadeDB Python Embedded Bindings
+
+A native Python bindings for ArcadeDB that embeds the Java database engine
+directly in the Python process using JPype.
+"""
+
+# Which build this is: 'jvm' (the arcadedb-jvm distribution, the Java engine through JPype) or 'native' (the
+# arcadedb distribution, the engine as a GraalVM native-image library). The import name is arcadedb for both.
+# `_native.distribution_backend()` is fixed when the wheel is built (the native wheel build flips one line in
+# `_native/__init__.py`). `__backend__` is the engine that runs now: ARCADEDB_BACKEND=native can switch it on in a
+# source checkout, where a developer loads a library they built themselves.
+from . import _native as _native_backend
+from ._dist_conflict import DISTRIBUTIONS as _DISTRIBUTIONS
+from ._dist_conflict import check as _check_distributions
+
+_DISTRIBUTION_BACKEND = _native_backend.distribution_backend()
+__backend__ = "native" if _native_backend.enabled() else "jvm"
+
+# Both distributions install a package named arcadedb into the same directory; pip overwrites one with the other
+# silently. Refuse to import when the other one is installed too, before anything else runs.
+_check_distributions(_DISTRIBUTION_BACKEND)
+
+# The installed distribution's version is the single source of truth: the
+# wheel is versioned from the release tag, while the generated _version.py
+# is derived from the engine jar's version (scripts/write_version.py), so the
+# two disagree on tagged releases
+# (a 26.8.1.dev20 wheel carried __version__ == "26.8.1.dev0"). Fall back to
+# the generated file, then to a placeholder, for source checkouts that were
+# never installed.
+try:
+    from importlib.metadata import version as _dist_version
+
+    __version__ = _dist_version(_DISTRIBUTIONS[_DISTRIBUTION_BACKEND])
+except Exception:  # not installed: fall back to the build-time file
+    try:
+        from ._version import __version__
+    except ModuleNotFoundError:
+        __version__ = "0.0.0"
+
+from ._build_info import ENGINE_VERSION, NATIVE_IMAGE, NATIVE_MARCH, SOURCE_COMMIT  # noqa: F401
+
+# Import async execution
+from .async_executor import AsyncExecutor
+
+# Import record event handle
+from .callbacks import EventHandle
+
+# Import core database classes
+from .core import (
+    Database,
+    DatabaseFactory,
+    create_database,
+    database_exists,
+    open_database,
+)
+
+# Import exceptions
+from .exceptions import ArcadeDBError
+
+# Import exporter classes
+from .exporter import export_database, export_to_csv
+
+# Import graph classes
+from .graph import Document, Edge, Vertex
+
+# Import graph batch helper
+from .graph_batch import GraphBatch
+
+# Import importer helpers
+from .importer import ImportResult
+
+# Which engine this install actually carries. __version__ is the PACKAGE
+# version and can disagree with the bundled JARs without any error.
+from .jvm import jar_fingerprint
+
+# Import result classes
+from .results import Result, ResultSet
+
+# Import schema classes
+from .schema import IndexType, PropertyType, Schema
+
+# Import server classes
+from .server import ArcadeDBServer, create_server
+
+# Import transaction management
+from .transactions import TransactionContext
+
+# Import type conversion utilities
+from .type_conversion import convert_java_to_python, convert_python_to_java
+
+# Import vector utilities and index
+from .vector import (
+    VectorIndex,
+    to_java_byte_array,
+    to_java_float_array,
+    to_java_int_array,
+    to_python_array,
+)
+
+__all__ = [
+    "__version__",
+    "ENGINE_VERSION",
+    "NATIVE_IMAGE",
+    "SOURCE_COMMIT",
+    "__backend__",
+    # Exceptions
+    "ArcadeDBError",
+    # Core classes
+    "Database",
+    "DatabaseFactory",
+    "EventHandle",
+    # Record wrappers
+    "Document",
+    "Vertex",
+    "Edge",
+    # Build provenance
+    "jar_fingerprint",
+    "create_database",
+    "open_database",
+    "database_exists",
+    # Result classes
+    "ResultSet",
+    "Result",
+    # Schema classes
+    "Schema",
+    "IndexType",
+    "PropertyType",
+    # Transaction management
+    "TransactionContext",
+    # Async execution
+    "AsyncExecutor",
+    "GraphBatch",
+    "ImportResult",
+    # Type conversion
+    "convert_java_to_python",
+    "convert_python_to_java",
+    # Vector search
+    "VectorIndex",
+    "to_java_byte_array",
+    "to_java_float_array",
+    "to_java_int_array",
+    "to_python_array",
+    # Server classes
+    "ArcadeDBServer",
+    "create_server",
+    # Data export
+    "export_database",
+    "export_to_csv",
+]

arcadedb/_build_info.py

@@ -0,0 +1,5 @@
+"""Written by native-wheel/build_wheel.py."""
+ENGINE_VERSION = "26.10.2"  # the ArcadeDB engine release compiled into libarcadedb.dll
+NATIVE_IMAGE = "GraalVM CE 25.4.4.1.1, -O2, -march=compatibility"
+NATIVE_MARCH = "compatibility"  # lib.py checks the CPU only for an x86-64-v3 image
+SOURCE_COMMIT = "00f29ff00e17670c21d9049755e9095cbe6c8eb2"  # ArcadeData/arcadedb-python commit of the bindings and the Java glue

arcadedb/_dist_conflict.py

@@ -0,0 +1,81 @@
+"""Refuse to import when both distributions that provide the `arcadedb` import are installed.
+
+This repository builds two distributions. `arcadedb` is the native build (the engine as a GraalVM native-image
+library, loaded with ctypes) and `arcadedb-jvm` is the JVM build (the Java engine in-process through JPype).
+Both put a package named `arcadedb` into the same site-packages directory, so installing one after the other
+overwrites files of the first with files of the second, and pip says nothing. What would be imported is a mix
+of two builds. Package metadata still lists both, so this module looks there and raises an ImportError that
+names both packages and says how to fix it, instead of letting the mix run.
+
+`check(backend)` is called first thing in `arcadedb/__init__.py`. `backend` is the build this code belongs to:
+"jvm" or "native".
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+from typing import Callable
+
+# backend -> the distribution that carries it
+DISTRIBUTIONS = {"native": "arcadedb", "jvm": "arcadedb-jvm"}
+
+# The page that explains the two packages (the "Which package?" page of the docs, linked from the README).
+DOCS_URL = "https://github.com/ArcadeData/arcadedb-python/blob/main/docs/modules/ROOT/pages/which-package.adoc"
+
+
+class DistributionConflictError(ImportError):
+    """Both the native `arcadedb` and the JVM `arcadedb-jvm` distribution are installed."""
+
+
+def other_backend(backend: str) -> str:
+    if backend not in DISTRIBUTIONS:
+        raise ValueError(f"backend must be 'jvm' or 'native', not {backend!r}")
+    return "jvm" if backend == "native" else "native"
+
+
+def installed(
+    backends: tuple[str, ...] = ("native", "jvm"),
+    lookup: Callable[[str], str] = metadata.version,
+) -> list[str]:
+    """The distribution names of `backends` that are installed, in the order given.
+
+    `lookup` raises `importlib.metadata.PackageNotFoundError` for a name that is not installed.
+    """
+    found = []
+    for backend in backends:
+        name = DISTRIBUTIONS[backend]
+        try:
+            lookup(name)
+        except metadata.PackageNotFoundError:
+            continue
+        found.append(name)
+    return found
+
+
+def message(backend: str) -> str:
+    own, other = DISTRIBUTIONS[backend], DISTRIBUTIONS[other_backend(backend)]
+    kind = {"native": "native", "jvm": "JVM"}
+    return (
+        f"The distribution '{own}' ({kind[backend]} build) cannot be imported while '{other}' "
+        f"({kind[other_backend(backend)]} build) is installed. "
+        f"Both provide the Python package 'arcadedb', so each install overwrote files of the other "
+        f"without a message, and what you would import is a mix of the two builds. "
+        f"Keep one: run 'pip uninstall {DISTRIBUTIONS['native']} {DISTRIBUTIONS['jvm']}', then install "
+        f"'{DISTRIBUTIONS['native']}' (native, the default for most embedded use) or "
+        f"'{DISTRIBUTIONS['jvm']}' (JVM, for heavy long-running loads). "
+        f"Which one to pick: {DOCS_URL}"
+    )
+
+
+def check(backend: str, lookup: Callable[[str], str] = metadata.version) -> None:
+    """Raise DistributionConflictError when the distribution of the other backend is installed too.
+
+    Never raises for anything else: an import must not fail because the metadata could not be read.
+    """
+    other = other_backend(backend)
+    try:
+        found = installed((other,), lookup)
+    except Exception:  # unreadable metadata, an odd sys.path entry: say nothing
+        return
+    if found:
+        raise DistributionConflictError(message(backend))

arcadedb/_jpype_stub.py

@@ -0,0 +1,44 @@
+"""Stand-in for ``jpype`` inside the native `arcadedb` wheel (generated package only).
+
+The Python sources are shared with ``arcadedb-jvm`` and import ``jpype`` at module level. The native wheel has no JVM and does
+not depend on JPype, so the build rewrites those imports to this module. Names resolve to placeholder classes: ``isinstance`` checks
+against them are simply False, and any attempt to call, subscript or build one raises :class:`NotOnNativeYet`. ``isJVMStarted()`` is
+always False. Code paths that need real JPype (``jvm_kwargs``, ``get_java_database``, Java-object APIs) are the JVM-only APIs listed in the README.
+"""
+
+from arcadedb._native import NotOnNativeYet
+
+
+class JException(Exception):
+    """Placeholder for ``jpype.JException`` (never raised here)."""
+
+
+class _Placeholder(type):
+    def __call__(cls, *a, **k):
+        raise NotOnNativeYet(
+            f"{cls.__name__} needs a JVM; this is the native build (the arcadedb wheel); the JVM build is arcadedb-jvm"
+        )
+
+    def __getitem__(cls, item):
+        raise NotOnNativeYet(
+            f"{cls.__name__}[...] needs a JVM; this is the native backend"
+        )
+
+    def __getattr__(cls, name):
+        if name.startswith("__"):
+            raise AttributeError(name)
+        raise NotOnNativeYet(
+            f"{cls.__name__}.{name} needs a JVM; this is the native backend"
+        )
+
+
+def isJVMStarted() -> bool:
+    return False
+
+
+def __getattr__(name: str):
+    if name.startswith("__"):
+        raise AttributeError(name)
+    ph = _Placeholder(name, (), {})
+    globals()[name] = ph
+    return ph

arcadedb/_logdir.py

@@ -0,0 +1,182 @@
+"""Where the engine writes its log, for both builds (the JVM build and the native build).
+
+The engine's own ``arcadedb-log.properties`` writes ``./log/arcadedb.log`` into the working directory. Both builds move the file
+log to a per-user directory instead: ``ARCADEDB_LOG_DIR`` if set, else ``arcadedb/log`` under the user's state directory. They
+write a ``logging.properties`` there whose file pattern is ``${arcadedb.server.logsDirectory}/arcadedb.log`` and point two
+system properties at it: ``arcadedb.server.logsDirectory`` (the directory) and ``java.util.logging.config.file`` (that file).
+The JVM build sets them as JVM arguments (``jvm.py``), the native build as isolate arguments (``_native/lib.py``). The engine
+reads both when it first logs, so they have to be in place before the first engine call. This module has no JVM and no JPype.
+
+The engine's console handler is off by default on Windows (``ARCADEDB_LOG_CONSOLE`` turns it on or off on any platform). On Windows
+the runtime caches the OS handle of stdout and stderr at start-up. A host that redirects fd 1 or 2 afterwards (pytest's fd capture,
+a service, an embedding application) closes that handle, a database file opened later can get the same handle value, and the next
+console log line is written into that file. The log file does not have that problem: the engine opens it itself.
+"""
+
+import os
+import re
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from ._logging import get_logger
+
+_LOGGER = get_logger(__name__)
+
+LOG_DIR_ENV = "ARCADEDB_LOG_DIR"
+LOG_CONSOLE_ENV = "ARCADEDB_LOG_CONSOLE"
+LOGGING_CONFIG_NAME = "logging.properties"
+# The config without the console handler has its own file name, so that two processes with different console settings that share a
+# log directory never replace each other's file between the write and the engine's first log call.
+FILE_ONLY_CONFIG_NAME = "logging-file-only.properties"
+CONSOLE_HANDLER = "java.util.logging.ConsoleHandler"
+
+# The engine's arcadedb-log.properties without its file pattern, for the native build: the image holds the engine's copy as a
+# resource, but an isolate argument has to name a real file, and there is no jar to read it from. tests/test_log_dir.py compares
+# this text with the file in the engine jar, so an engine upgrade that changes the file fails there until this is updated.
+NATIVE_ENGINE_LOG_PROPERTIES = """\
+handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler
+.level = INFO
+io.undertow.level=WARNING
+org.xnio.level=WARNING
+org.jboss.level=WARNING
+org.apache.ratis.grpc.server.GrpcLogAppender.level = SEVERE
+com.arcadedb.level = INFO
+java.util.logging.ConsoleHandler.level = INFO
+java.util.logging.ConsoleHandler.formatter = com.arcadedb.utility.AnsiLogFormatter
+java.util.logging.FileHandler.level = INFO
+java.util.logging.FileHandler.formatter = com.arcadedb.log.LogFormatter
+java.util.logging.FileHandler.limit=100000000
+java.util.logging.FileHandler.count=10
+"""
+
+
+def state_base_dir() -> Path:
+    """Per-user base directory for state and logs, by platform (stdlib only).
+
+    The home directory is read only where the platform needs it, and when it
+    cannot be determined (no HOME or USERPROFILE, as in a stripped-down service
+    environment) the system temp directory is used, so this never raises.
+    """
+    if sys.platform == "win32":
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            return Path(local)
+    elif sys.platform != "darwin":
+        xdg = os.environ.get("XDG_STATE_HOME")
+        # The XDG spec ignores a relative value.
+        if xdg and os.path.isabs(xdg):
+            return Path(xdg)
+    try:
+        home = Path.home()
+    except (RuntimeError, KeyError, OSError):
+        return Path(tempfile.gettempdir())
+    if sys.platform == "win32":
+        return home / "AppData" / "Local"
+    if sys.platform == "darwin":
+        return home / "Library" / "Logs"
+    return home / ".local" / "state"
+
+
+def default_log_dir() -> Path:
+    """Where the engine log, the crash log and logging.properties go.
+
+    ``ARCADEDB_LOG_DIR`` if set, else ``arcadedb/log`` under the
+    per-user state directory. Never the working directory.
+    """
+    override = os.environ.get(LOG_DIR_ENV)
+    if override:
+        return Path(os.path.abspath(os.path.expanduser(override)))
+    return state_base_dir() / "arcadedb" / "log"
+
+
+def console_enabled() -> bool:
+    """Whether the engine logs to the console (stdout/stderr) as well as to its log file.
+
+    ``ARCADEDB_LOG_CONSOLE`` decides on every platform: ``1``, ``true``, ``yes`` or ``on`` turns the console handler on; ``0``,
+    ``false``, ``no`` or ``off`` turns it off. Unset (or any other value), it is on everywhere except Windows, where it is off
+    (see the module docstring for why). A ``java.util.logging.config.file`` the caller passes replaces all of this.
+    """
+    value = os.environ.get(LOG_CONSOLE_ENV, "").strip().lower()
+    if value in ("1", "true", "yes", "on"):
+        return True
+    if value in ("0", "false", "no", "off"):
+        return False
+    return sys.platform != "win32"
+
+
+def logging_config_name(console: Optional[bool] = None) -> str:
+    """The file name of the generated logging config: ``logging.properties`` with the console handler, ``logging-file-only.properties`` without."""
+    if console is None:
+        console = console_enabled()
+    return LOGGING_CONFIG_NAME if console else FILE_ONLY_CONFIG_NAME
+
+
+def render_logging_config(engine_text: str, console: Optional[bool] = None) -> str:
+    """The engine's logging config with the file log in ``logsDirectory``, and without the console handler unless ``console``.
+
+    The jar's own file hard-codes ``./log/arcadedb.log``, which lands in the
+    working directory. The engine resolves ``${arcadedb.server.logsDirectory}``
+    in the pattern, and the argument that sets it is added by the caller.
+    ``console`` None means :func:`console_enabled`.
+    """
+    if console is None:
+        console = console_enabled()
+    lines = []
+    for line in engine_text.splitlines():
+        if re.match(r"\s*java\.util\.logging\.FileHandler\.pattern\s*[=:]", line):
+            continue
+        if not console:
+            handlers = re.match(r"(\s*handlers\s*[=:]\s*)(.*)$", line)
+            if handlers:
+                kept = [
+                    h
+                    for h in re.split(r"[,\s]+", handlers.group(2).strip())
+                    if h and h != CONSOLE_HANDLER
+                ]
+                line = f"{handlers.group(1)}{', '.join(kept)}"
+            elif re.match(r"\s*java\.util\.logging\.ConsoleHandler\.", line):
+                continue
+        lines.append(line)
+    lines.append(
+        "java.util.logging.FileHandler.pattern="
+        "${arcadedb.server.logsDirectory}/arcadedb.log"
+    )
+    return "\n".join(lines) + "\n"
+
+
+def usable_log_dir(log_dir: Path) -> Path:
+    """Create the log directory; return it, or a fresh directory under the system temp directory when it cannot be created or
+    written (a read-only home, for example), so that nothing is ever written to the working directory.
+    """
+    try:
+        log_dir.mkdir(parents=True, exist_ok=True)
+        if not os.access(log_dir, os.W_OK | os.X_OK):
+            raise OSError(f"{log_dir} is not writable")
+    except OSError as exc:
+        fallback = Path(tempfile.mkdtemp(prefix="arcadedb-log-"))
+        _LOGGER.warning(
+            "Cannot use %s for ArcadeDB logs (%s); using %s. Set %s to choose one.",
+            log_dir,
+            exc,
+            fallback,
+            LOG_DIR_ENV,
+        )
+        return fallback
+    return log_dir
+
+
+def write_logging_config(log_dir: Path, engine_text: str) -> None:
+    """Write the logging config in ``log_dir`` under :func:`logging_config_name` (replaced atomically, and only when its text changed)."""
+    console = console_enabled()
+    name = logging_config_name(console)
+    config = log_dir / name
+    rendered = render_logging_config(engine_text, console)
+    try:
+        if not config.exists() or config.read_text("iso-8859-1") != rendered:
+            tmp = log_dir / f"{name}.{os.getpid()}.tmp"
+            tmp.write_text(rendered, encoding="iso-8859-1", newline="\n")
+            os.replace(tmp, config)
+    except OSError as exc:
+        _LOGGER.warning("Cannot write %s: %s", config, exc)

arcadedb/_logging.py

@@ -0,0 +1,23 @@
+"""Internal logging helpers for arcadedb.
+
+Centralises the pattern for swallowing exceptions in finalizers and
+best-effort cleanup paths so the suppression is observable at DEBUG level
+instead of being silently dropped.
+"""
+
+import logging
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a namespaced logger for an arcadedb submodule."""
+    return logging.getLogger(name)
+
+
+def log_swallowed_exception(logger: logging.Logger, context: str) -> None:
+    """Log the currently-handled exception at DEBUG with full traceback.
+
+    Use only inside an `except` block where the caller has decided the
+    error is non-fatal (e.g. JVM finalizer paths, optional best-effort
+    rollback) and continuing is the right behaviour.
+    """
+    logger.debug("Swallowed exception %s", context, exc_info=True)

arcadedb/_native/__init__.py

@@ -0,0 +1,53 @@
+"""The native backend: the engine as a GraalVM native-image shared library (``libarcadedb``) that Python loads with ``ctypes``. No JVM, no JPype.
+
+It is the only backend of the ``arcadedb`` wheel. In a source checkout or in the ``arcadedb-jvm`` wheel, ``ARCADEDB_BACKEND=native`` selects it
+(with ``ARCADEDB_NATIVE_LIB`` pointing at a library you built); the default there is JPype. The public API is the JVM build's, and the same
+test suite (``tests/``) runs against both.
+
+On native: databases and the factory, ``query``/``command`` (SQL and openCypher), transactions and ``run_in_transaction``, results as rows,
+columns and Arrow, pandas, polars and numpy frames, the ``Document``/``Vertex``/``Edge`` wrappers, the schema (types, properties, indexes),
+vector indexes (``find_nearest``, the PQ ``find_nearest_approximate``, ``get_metadata``, ``get_stats``), ``insert_many``, ``GraphBatch``,
+the ``AsyncExecutor`` (``transaction`` included), Python functions in SQL and record callbacks, importers and exporters, and the in-process
+server.
+
+Not on native, by design (each raises :class:`NotOnNativeYet`): the Java objects of the JVM build. These are ``get_java_database``,
+``get_java_document``, and the Java object a ``Schema``, type or index method returns where the native wrapper has no such method.
+There is no JVM to start or tune: ``jvm_kwargs`` is ignored with a warning.
+"""
+
+import os
+
+
+class NotOnNativeYet(NotImplementedError):
+    """The call hands out a Java object of the JVM build (``get_java_database``, ``get_java_document``, a Schema method's Java object), which the native build does not have."""
+
+
+# The backend used when ARCADEDB_BACKEND is unset. "jpype" here, which is the arcadedb-jvm wheel; the build of the native
+# `arcadedb` wheel (native/wheel/build_wheel.py) rewrites this one line to "native".
+_DEFAULT_BACKEND = "native"
+
+
+def distribution_backend() -> str:
+    """The build this code was packaged as: "native" (the `arcadedb` distribution) or "jvm" (the `arcadedb-jvm` distribution).
+
+    Fixed when the wheel is built. ``ARCADEDB_BACKEND`` does not change it: the distribution check in ``arcadedb/__init__.py``
+    asks which package this file belongs to, not which engine a developer switched on.
+    """
+    return "native" if _DEFAULT_BACKEND == "native" else "jvm"
+
+
+def enabled() -> bool:
+    """True when the native backend is selected: ``ARCADEDB_BACKEND=native``, or unset in the `arcadedb` (native) wheel (read at call time, so a test can switch it)."""
+    return os.environ.get("ARCADEDB_BACKEND", _DEFAULT_BACKEND).lower() == "native"
+
+
+def needs_jvm(what: str):
+    """A call that hands out a Java object of the JVM build. Native has no JVM, by design: the message names the build that has it."""
+    raise NotOnNativeYet(
+        f"{what} needs the JVM build (the arcadedb-jvm package); this is the native build (the arcadedb package)"
+    )
+
+
+def not_yet(what: str):
+    """A feature the native build is still missing (none today). A final release allows no test that ends here."""
+    raise NotOnNativeYet(f"{what} is not on the native backend yet")

arcadedb/_native/bulk.py

@@ -0,0 +1,71 @@
+"""Columnar bulk insert through one crossing (``arcadedb_n_insert_colp``): whole columns go over by address, with no JSON text. Numpy
+ints, floats and bools, lists of one value type (None is a null), strings (UTF-8 bytes plus offsets, as Arrow lays them out), float32
+vector columns and Arrow arrays are laid out by :mod:`.columnar`; anything else (nested values, mixed-type columns, date-times,
+decimals, integers past 64 bits) returns None and the caller uses the per-row JSON path. The documents are built image-side as
+``DocumentBatcher.insertColumns`` builds them on JPype. ``ARCADEDB_NATIVE_BULK=0`` turns the columnar path off.
+"""
+
+import os
+
+from . import columnar, lib
+
+_ENABLED = os.environ.get("ARCADEDB_NATIVE_BULK", "1") != "0"
+
+
+def _usable():
+    return (
+        _ENABLED
+        and columnar._np is not None
+        and lib._lib is not None
+        and hasattr(lib._lib, "arcadedb_n_insert_colp")
+    )
+
+
+def _send(db, type_name, packed, rows, commit_every, prefix):
+    from .database import _call
+
+    spec = columnar.spec_of(packed)
+    reply = _call(
+        prefix,
+        "arcadedb_n_insert_colp",
+        db._h,
+        lib.b(type_name),
+        lib.b(columnar.header_of(rows, commit_every, packed)),
+        spec,
+        len(spec),
+    )  # `packed` holds the arrays the addresses point into until the call returns
+    return int(reply["n"])
+
+
+def insert_columns_fast(
+    db, type_name, columns, commit_every, declared=None, prefix="Failed to bulk-insert"
+):
+    """Insert ``columns`` (name -> column) in one crossing and return the row count, or None when a column cannot be sent this way.
+
+    ``declared``: a dict of declared property types when the caller already knows them (the DataFrame path), else they are read from the
+    schema if a column needs them.
+    """
+    if not _usable():
+        return None
+    packed = columnar.pack(columns, columnar.Declared(db, type_name, declared))
+    if packed is None:
+        return None
+    rows, cols = packed
+    return _send(db, type_name, cols, rows, commit_every, prefix)
+
+
+def insert_rows_columnar(db, type_name, chunk):
+    """One ``insert_many`` chunk (a list of dicts with the same keys) through the columnar entry inside the caller's transaction (no
+    commit here). Returns True when it was sent, False when the chunk needs the JSON path.
+    """
+    if not _usable():
+        return False
+    columns = columnar.rows_to_columns(chunk)
+    if columns is None:
+        return False
+    packed = columnar.pack(columns, columnar.Declared(db, type_name))
+    if packed is None:
+        return False
+    rows, cols = packed
+    _send(db, type_name, cols, rows, 0, f"Failed to bulk-insert into '{type_name}'")
+    return True