Metadata-Version: 2.5
Name: dynamodb-haystack
Version: 1.0.0
Summary: Haystack integration for dynamodb
Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/dynamodb#readme
Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/dynamodb
Author-email: deepset GmbH <info@deepset.ai>
License-Expression: Apache-2.0
License-File: LICENSE.txt
Keywords: aws,document-store,dynamodb,haystack,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
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 :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: aiobotocore<4,>=3.9.1
Requires-Dist: boto3<2,>=1.43.66
Requires-Dist: haystack-ai>=3.0.0
Description-Content-Type: text/markdown

# dynamodb-haystack

[![PyPI - Version](https://img.shields.io/pypi/v/dynamodb-haystack.svg)](https://pypi.org/project/dynamodb-haystack)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/dynamodb-haystack.svg)](https://pypi.org/project/dynamodb-haystack)

- [Integration page](https://haystack.deepset.ai/integrations/dynamodb)
- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/dynamodb/CHANGELOG.md)

---

## Requirements

DynamoDB's native vector search (`SearchVectors`, vector indexes) is only available in
`boto3 >= 1.43.66`, which requires Python 3.10+. Both are enforced by this package's metadata.

## Limitations

- Metadata filters are evaluated client-side: `filter_documents`, `count_documents` and the
  filter-based bulk operations scan the whole table, and embedding retrieval filters the at most
  100 nearest candidates that DynamoDB's `SearchVectors` returns (`top_k` cannot exceed 100).
- Only cosine similarity is supported for now.
- A DynamoDB item is limited to 400 KB, which bounds a document's content, metadata and embedding.

## Running the integration tests

The integration tests run against **real AWS** — there is no local DynamoDB emulator that
supports vector indexes. They are skipped unless you opt in:

```bash
export AWS_DEFAULT_REGION=<your-region>
export HAYSTACK_DYNAMODB_INTEGRATION_TESTS=1
hatch run test:integration
```

You also need credentials (any standard boto3 credential source) with permission to
`CreateTable`, `DeleteTable`, `DescribeTable`, `ListTables`, the item-level operations, and
`SearchVectors`. Each test class creates one table named `haystack_test_<run id>_<class>` and
deletes it afterwards; a session-scoped safety net sweeps any table of the same run whose delete
was rejected while its index was still settling. Expect the suite to create and destroy real,
billable tables.

## Contributing

Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).