Connections
Connect an Amazon S3 bucket you own and read its files into Nexus without copying them first.
A connection lets read data where it lives, in an Amazon S3 bucket your organisation owns. You never hand Klarety a secret: a policy on your bucket grants read access, and you can revoke it any time.
Use one when data is too large to upload, changes in place, or must stay in your account. For other services (a CRM, a database, a SaaS tool), see Connectors.
Before you start
- You are a owner or admin. Only they add connections; other members use the ones they were given.
- You can change the bucket's policy in your AWS account, or ask someone who can.
- You know the bucket's name and region, and optionally the folder (prefix) Nexus may read.
Connect a bucket
Create the connection
from klarety import Nexus, RefusedError
with Nexus.connect() as nexus:
try:
connection = nexus.connections.create(
"sales-exports",
bucket="acme-sales-exports",
region="us-east-1",
prefix="exports/",
)
except RefusedError as refused:
raise SystemExit(f"Could not add the connection: {refused}")
connection_id = connection["connection_id"]
print(connection_id)prefix limits the connection to one folder of the bucket. writable=True lets Nexus write back too; it is off by default, and your bucket policy must also allow it.
Add the bucket policy
grant = nexus.connections.grant_policy(connection_id)
print(grant["policy"])Add the policy to the bucket in your AWS account. It allows Klarety to read only this bucket and prefix.
Test it
check = nexus.connections.test(connection_id)
print(check["reachable"], check["reason"])test() never raises on an unreachable bucket. It answers reachable and, when False, a reason to act on, such as a missing policy or a wrong region.
Browse and load
for entry in nexus.connections.browse(connection_id, "exports/2026/"):
kind = "folder" if entry["is_prefix"] else entry["format_name"]
print(entry["key"], kind, entry["size_bytes"])
result = nexus.connections.read(
connection_id, "exports/2026/11.parquet", into="sales", key=["order_id"]
)
print(result)browse() lists one level at a time, up to 200 entries, and never goes above the connection's prefix. read() loads one file through the same ingest as an upload, reading it in place without copying. Follow the load as in Ingest data.
Write back to your bucket
For a writable connection, plan_write() shows where rows would land and what your policy still must allow, before writing:
plan = nexus.connections.plan_write(connection_id, "exports/summaries/")
print(plan)Manage connections
for one in nexus.connections.list():
print(one["connection_id"], one["name"], one["kind"])
print(nexus.connections.describe(connection_id))
nexus.connections.delete(connection_id)Deleting a connection removes it from Klarety. To cut access from your side too, remove the bucket policy.
Who can use a connection
Owners and admins reach every connection. Give other people access to a connection in Data access in Settings; anyone without access gets NotFoundError, as if the connection did not exist.
What can go wrong
| Problem | Cause | Fix |
|---|---|---|
RefusedError on create() | You are not an owner or admin, or the bucket details are invalid. The message says which. | Ask an admin, or correct the details. |
test() answers reachable: False | The policy is missing or the region is wrong. | Read reason, fix it, test again. |
NotFoundError | No such connection, or you have no access to it. | Check the ID, or ask for access. |
| A write is refused | The connection is not writable, or the bucket policy does not allow writing. | Create it with writable=True and update the policy. |
Next steps
- Ingest data for load modes and keys.
- Files and folders for files you keep in Klarety.
- Run SQL to query what you loaded.