# Connections

A connection lets <Term id="nexus">Nexus</Term> 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](/docs/connectors).

## Before you start [#before-you-start]

- **You are a <Term id="workspace">workspace</Term> 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 [#connect-a-bucket]

<Steps>
<Step>
### Create the connection [#create-the-connection]

```python
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.
</Step>
<Step>
### Add the bucket policy [#add-the-bucket-policy]

```python
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.
</Step>
<Step>
### Test it [#test-it]

```python
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.
</Step>
</Steps>

## Browse and load [#browse-and-load]

```python
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](/docs/developers/ingest).

## Write back to your bucket [#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:

```python
plan = nexus.connections.plan_write(connection_id, "exports/summaries/")
print(plan)
```

## Manage connections [#manage-connections]

```python
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.

<Callout type="info" title="Who can use a connection">
Owners and admins reach every connection. Give other people access to a connection in **Data access** in <AppLink to="settings" />; anyone without access gets `NotFoundError`, as if the connection did not exist.
</Callout>

<Screenshot src="/docs/_media/manage-connections-by-toggle-on-off-per-project.png" alt="Data access in Settings, granting a person access to an Amazon S3 connection" />

## What can go wrong [#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 [#next-steps]

- [Ingest data](/docs/developers/ingest) for load modes and keys.
- [Files and folders](/docs/developers/files) for files you keep in Klarety.
- [Run SQL](/docs/developers/sql) to query what you loaded.