Read and write data objects from a function
A function runtime can read and write data objects on the same distribution through host-mediated env.document calls. Grants decide which script may touch which key, whether the object is public (visitors can GET it when a route or fallback serves it) or private (never served to visitors), and whether access is read-only or read-write.
Grants live outside the function source. Handler code cannot create, change, or bypass a grant. Setting a grant needs function.write (edge_document_grant_set or edge_document_prefix_set). document.write alone is not enough.
Function grants and private data objects are not managed in the web console yet. Use an agent or MCP.
This page assumes a distribution with at least one compiled function runtime. If not, start with Add an endpoint. Throughout, that distribution is acme-marketing (d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38) and the handler script is 01JBQZ8XKT4A9WN2CDEFGH5RM7.
1. Write a public object (when visitors should read it)
For a public grant on one key, the object must already exist under the public store (the same files you manage with edge_document_write).
On acme-marketing, store a data object menu.json with
{"title":"Lunch"} and show me the etag.edge api PUT /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents --input - <<'EOF'
{
"documents": [
{
"path": "menu.json",
"content": "{\"title\":\"Lunch\"}"
}
]
}
EOFcurl -s -X PUT \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{
"path": "menu.json",
"content": "{\"title\":\"Lunch\"}"
}
]
}'The agent runs edge_document_write. This does not grant the function access yet.
2. Grant the function access
Pick mode read or read-write, visibility public or private, and optionally a scripts list that names script ids and read or write access. When scripts is omitted, every function on the distribution receives the mode's access. Use mode none to remove a sidecar grant.
| Visibility | Visitor GET /_api | Typical use |
|---|---|---|
public | Yes, when mapped or via the GET fallback | Shared JSON the page and a function both use |
private | No — 404 even if a route matched | Notes, drafts, counters only the function should touch |
You cannot change visibility on an existing grant. Public read-write keys are served with cache-control: no-store so a cached copy does not hide writes from your function.
On acme-marketing, grant script 01JBQZ8XKT4A9WN2CDEFGH5RM7 read access
to the public data object menu.json.On acme-marketing, set a private prefix grant on notes/ for script
01JBQZ8XKT4A9WN2CDEFGH5RM7 with read-write access.The agent runs edge_document_grant_set or edge_document_prefix_set. A prefix grant covers every key under it, including keys the function creates later. At most 32 prefix grants and 32 scripts per sidecar grant apply; see Limits.
For private keys, seed content with edge_private_document_write after the private grant exists. Those tools read and write the private store only — not the public edge_document_* paths.
3. Call env.document from the handler
handler receives the stores as its second argument, env. JavaScript and Python both expose env.document (the older edge.document global is the same object). Python raises DocumentError with a .code field when the platform refuses the call.
| Method | Purpose |
|---|---|
get(key) | Returns {body, etag} |
put(key, body, ifMatch?) | Returns {etag}. Send the previous etag as ifMatch to detect concurrent writers |
list(prefix, cursor?) | Returns {keys, cursor} — pages of up to 50 keys |
delete(key) | Returns {deleted: true} |
At most eight host calls run per invocation, shared with env.kv and env.sql. Each body is capped at 1 MiB, the same as a public data object.
function handler(request, env) {
var doc = env.document.get('menu.json');
return {
statusCode: 200,
headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
body: JSON.stringify({ menu: JSON.parse(doc.body), etag: doc.etag }),
};
}Common error codes on error.code (JavaScript) or DocumentError.code (Python):
| Code | Meaning |
|---|---|
denied | No grant, script not listed, or access too weak — including get on a missing key |
not_found | Grant allows the call but the object is absent (except denied-without-grant on get) |
etag_mismatch | ifMatch did not match the stored object |
etag_required | Update requires an etag but none was sent |
already_exists | Create conflict on a key that already exists |
Map the function onto /_api with Add an endpoint. Test with edge_function_invoke before you rely on a public path.
4. Inspect grants
Show the function grant for menu.json on acme-marketing and list
all prefix grants.The agent runs edge_document_grant_get and edge_document_prefix_get (function.read).
Next
- Function runtimes — sandbox caps and outbound HTTPS
- Serve a data object — public objects without a function
- Use key-value and SQL storage from a function — counters, sessions and queryable tables
- Endpoints — how
/_apiroutes relate to data objects