{"id":9360,"library":"tiledb","title":"TileDB Python API","description":"TileDB-Py is the official Python interface to the TileDB Storage Engine, an efficient multi-dimensional array management system. It provides a Pythonic API for storing and accessing dense and sparse array data, featuring fast updates, reads, excellent compression, and efficient parallel I/O with high scalability. The library is actively maintained, with version 0.36.1 released on February 25, 2026, and regular updates.","status":"active","version":"0.36.1","language":"en","source_language":"en","source_url":"https://github.com/TileDB-Inc/TileDB-Py","tags":["data storage","arrays","scientific computing","dense arrays","sparse arrays","cloud storage","high performance computing"],"install":[{"cmd":"pip install tiledb","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Required for DataFrame functionality (tiledb.from_pandas, Array.df[]).","package":"pandas","optional":true},{"reason":"Required for DataFrame functionality (tiledb.from_pandas, Array.df[]).","package":"pyarrow","optional":true},{"reason":"Core dependency for array operations, automatically built from source during pip install if not present.","package":"numpy","optional":false},{"reason":"Core dependency for compilation, automatically built from source during pip install if not present.","package":"cython","optional":false}],"imports":[{"symbol":"tiledb","correct":"import tiledb"},{"note":"Primarily for accessing native library details like version; not for general array operations.","symbol":"libtiledb","correct":"import tiledb.libtiledb"}],"quickstart":{"code":"import tiledb\nimport numpy as np\nimport os\n\n# Define array URI\narray_uri = \"my_dense_array\"\n\n# Clean up previous array if it exists\nif os.path.exists(array_uri):\n    tiledb.remove(array_uri)\n\n# 1. Create a dense array schema\ndom = tiledb.Domain(\n    tiledb.Dim(name=\"rows\", domain=(1, 4), tile=4, dtype=np.int32),\n    tiledb.Dim(name=\"cols\", domain=(1, 4), tile=4, dtype=np.int32)\n)\nattr = tiledb.Attr(name=\"data\", dtype=np.int32)\nschema = tiledb.ArraySchema(domain=dom, attrs=[attr], sparse=False)\n\n# 2. Create the array\ntiledb.DenseArray.create(array_uri, schema)\n\n# 3. Write data to the array\nwith tiledb.DenseArray(array_uri, mode=\"w\") as A:\n    data = np.array([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]])\n    A[:] = data\n\n# 4. Read data from the array (slice)\nwith tiledb.DenseArray(array_uri, mode=\"r\") as A:\n    # Read a slice (e.g., rows 1-2, cols 2-3)\n    subset = A[1:3, 2:4]\n    print(\"Read subset:\")\n    print(subset)\n\n# Clean up\ntiledb.remove(array_uri)\n","lang":"python","description":"This quickstart demonstrates how to create a TileDB dense array, write NumPy data to it, and read a slice of the data. The array is stored locally on disk."},"warnings":[{"fix":"Ensure your project's `pandas` dependency is pinned to `<3.0.0` or update TileDB-Py when compatibility with `pandas` 3.x is officially released.","message":"TileDB-Py 0.36.1 and later versions restrict the compatible `pandas` library to versions below 3 (`pandas < 3`). Users attempting to install or run with `pandas` 3.0 or higher may encounter dependency resolution issues or unexpected behavior.","severity":"breaking","affected_versions":">=0.36.1"},{"fix":"Be patient during installation. For verbose output to monitor the build process, add the `-v` flag: `pip install -v tiledb`. Consider pre-installing `numpy` and `cython` if you anticipate issues, or using `conda` for a potentially faster installation via pre-built binaries (`conda install -c conda-forge tiledb-py`).","message":"Initial installation via `pip install tiledb` can take a significant amount of time, as the package automatically downloads and builds the native TileDB C++ library along with Python bindings. If `numpy` and `cython` are not pre-installed, `pip` may also build them from source, further increasing install time.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify that cloud storage credentials (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `GOOGLE_APPLICATION_CREDENTIALS`) are correctly set in the environment where the Python script is run. Ensure the TileDB `Config` object is properly initialized with VFS-specific settings like `vfs.s3.region` or `vfs.gcs.project_id` if required.","message":"When working with cloud storage (e.g., S3, GCS), incorrect configuration of credentials or environment variables can lead to `TileDBError: [TileDB::Array] Error: Cannot open array; Array does not exist`, even if the URI format is correct and local operations succeed.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"For reads, try reading data in smaller chunks or slices rather than the entire array at once. For writes or consolidations, ensure adequate system memory (RAM) is available or optimize array schema parameters (e.g., tile capacity, compression) to reduce memory footprint. If processing very large datasets, consider distributed computing frameworks or memory-mapping options if applicable.","cause":"This error typically indicates an out-of-memory condition when attempting to read or process large TileDB arrays, particularly when loading entire arrays into memory or during consolidation operations without sufficient resources.","error":"TileDBError: Error: Internal TileDB uncaught exception; std::bad_alloc"},{"fix":"Double-check the array URI for correctness, including any file system paths or cloud storage bucket/object prefixes. Verify that the current user/process has read/write permissions to the specified location. For cloud storage, ensure authentication (e.g., AWS credentials, GCP service account) is correctly configured and accessible to the TileDB process.","cause":"This error most commonly occurs when the provided URI for a TileDB array does not point to an existing array. This can be due to a typo in the URI, incorrect file paths, or insufficient permissions. When using cloud storage, it often relates to authentication/authorization issues or incorrect bucket/path specifications.","error":"TileDBError: [TileDB::Array] Error: Cannot open array; Array does not exist"},{"fix":"Access properties of `tiledb.Dim` using dot notation (e.g., `dim.name`, `dim.domain`, `dim.dtype`) instead of attempting to index into the object directly. The `tiledb.Domain` object, which contains dimensions, is subscriptable to access dimensions by index or name.","cause":"This error indicates an attempt to treat a `tiledb.Dim` object as if it were a sequence or dictionary (e.g., trying to index into it with `[]`), rather than accessing its properties directly.","error":"TypeError: 'Dimension' object is not subscriptable"}]}