afy collections, index, and points
The Aetherfy CLI’s vector commands
Three command groups of the Aetherfy CLI read and manage the Aetherfy vector
database, with the same API key as every other afy command. They cover
inspecting collections, creating and deleting them, managing payload indexes,
browsing and reading points, writing a few, and deleting them. Bulk loading
is not among them: the Python and JavaScript SDKs do that, with the chunking
and retries a bulk load needs (see /vectors/sdk).
| Command | Purpose |
|---|---|
afy collections list | List the collections in a workspace |
afy collections get <name> | Show one collection |
afy collections create <name> | Create a collection |
afy collections delete <name> | Delete a collection and every point in it |
afy collections restore-points [collection] | List the copies a collection can be restored from, or the deleted collections |
afy collections restore <restore-point> | Restore a restore point, a deleted collection’s or a daily copy, as a new collection |
afy collections regions <name> | Change the regions a collection’s data is placed in, after a preview |
afy collections region-limits | Show your plan’s region-change limits, and how much of them you have used |
afy collections update <name> | Rename a collection, or change its description |
afy collections schema get <name> | Show a collection’s payload schema and its version |
afy collections schema set <name> | Set the schema from a file |
afy collections schema delete <name> | Delete the schema (the points are not touched) |
afy collections schema analyze <name> | Sample the points and suggest a schema |
afy collections move <name> | Move a collection to another workspace |
afy collections protect <name> | Protect a collection: no agent’s key may delete it or remove data from it |
afy collections unprotect <name> | Turn protection off, after asking |
afy index create <collection> <field> | Index one payload field, and wait until the index is built |
afy index delete <collection> <field> | Drop the payload index on one field |
afy points count <collection> | Count the points, or those a filter matches |
afy points list <collection> | Page through the points in a collection, with their payloads |
afy points get <collection> <id>... | Read points by id, with their payloads |
afy points search <collection> | Find the points nearest to a vector |
afy points upsert <collection> | Add points, or replace them by id |
afy points delete <collection> <id>... | Delete points by id, or the points a filter matches |
The collections group also answers to collection.
Flags every Aetherfy vector command takes
Each of the twenty commands takes these four flags, in addition to the global flags on /cli.
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | Print one JSON object with stable field names. It is the root flag, accepted on every command |
--workspace | string | the account’s only workspace; asked when there are several | Workspace the collection names belong to. Required without a terminal, and with --json, when the account has several |
--vectors-url | string | see below | Aetherfy vectors API endpoint |
--api-region | string | AETHERFY_VECTORS_API_REGION | API region to connect to: us-east-1, eu-central-1 or ap-southeast-1 |
How the Aetherfy CLI chooses the vectors endpoint
The Aetherfy CLI picks the endpoint in the same order as the Aetherfy SDKs:
--vectors-url, when given.AETHERFY_VECTORS_URL, when set. It also wins over an API region, with a warning on stderr: Aetherfy sets this variable on every agent machine.--api-region, elseAETHERFY_VECTORS_API_REGION. The region is turned into a URL by askingGET /api/v1/regionsonhttps://vectors.aetherfy.com.https://vectors.aetherfy.com.
An API region outside the three above is refused before any request, with exit
code 2. The API region only chooses which Aetherfy endpoint answers; it is not
where a collection’s data lives, which afy collections create --regions sets.
How the Aetherfy CLI chooses the workspace
Every Aetherfy collection lives in one workspace, and its name is unique there:
articles in workspace research and articles in workspace default are two
collections, and a command finds the one in the workspace it acts in. Every
collections, index and points command acts in a workspace:
--workspace <name>names it.- Without the flag, an account with one workspace uses it, and you never name it.
- With several, you are asked to pick one. Without a terminal, or with
--json, there is nobody to ask, so--workspaceis required: the command exits2and sends nothing, naming the workspaces to choose from. - No environment variable sets it.
AETHERFY_WORKSPACEis not read, and an empty--workspace ""is refused (exit2). A--workspaceor--tovalue starting with-is refused too, before anything is sent.
Every --json object says which endpoint and workspace the command used:
{
"endpoint": "https://vectors.aetherfy.com",
"workspace": "research",
"collections": []
}workspace is the workspace the command acted in.
Listing and inspecting Aetherfy collections
afy collections list lists the collections in the chosen workspace and no
others.
afy collections list
afy collections list --workspace research --jsonThe table has a Protected column that reads PROTECTED for a
protected collection. Each entry
of collections in the --json output carries name, description (or
null), size, distance, status, points_count, protected and
created_at. An empty result is "collections": [].
afy collections get <name> shows one collection, with its id (ID:) and the
change running on it, if any (Change:): a regions change or a move, whoever
started it — the dashboard, another terminal, a script without --wait. For
example replicating to us-east-1, eu-central-1 (in progress, operation …), or
moving to workspace 'research' (pending, operation …). Poll that operation as
/agents/api-workspaces describes. The line is absent
when nothing runs, and reads could not be read: … when the control plane could
not be asked; it never reads as “nothing running” then.
It also says whether the collection is protected (Protected:). Its --json output holds one collection object with the same fields plus id,
regions and updated_at, and operation: the running change (operation_id,
kind — regions_change or move —, status, from_regions, to_regions,
target_workspace as an {id, name} pair or null, accepted_at), or null
when none runs. When the change could not be read, operation_error carries why.
afy collections get articles --jsonCreating and deleting Aetherfy collections
afy collections create <name> creates a collection for vectors of one size,
compared with one distance.
| Flag | Type | Default | Description |
|---|---|---|---|
--size | int | none, required | Vector size in dimensions, above 0 |
--distance | string | none, required | cosine, dot, euclid or manhattan |
--regions | strings | every region your plan or workspace covers | Comma-separated regions to place the collection in, a subset of your plan’s regions |
afy collections create articles --size 1536 --distance cosine
afy collections create articles --size 768 --distance dot --regions us-east-1,eu-central-1 --jsonThe --json output’s collection holds name, size, distance and the
regions Aetherfy placed the collection in. Creating a collection that already
exists with the same settings succeeds and changes nothing.
afy collections delete <name> deletes a collection and every point in it. It
asks you to type the collection’s name first, and before the question it names the
agents that read or wrote the collection in the last 35 days (Used by agent '<name>' in the last 35 days.). That is a warning, never a refusal: the delete is
yours to make. If the warning cannot be read, the command says so and still asks.
--yes skips the question, not the warning: the same lines go to stderr (a
collection that does not exist is its own 404 either way), so a script’s log
records who used what it deleted.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--yes | -y | bool | false | Delete without asking |
When stdin is not a terminal, nobody can answer the question, so without
--yes the Aetherfy CLI deletes nothing and exits 2, before asking: This deletes collection '<name>' and every point in it; pass --yes to confirm without a prompt. Typing another name cancels: exit 1 with Cancelled: the name typed did not match, nothing deleted, and under --json an error document with a message
and the code CLI_CANCELLED. A script passes --yes:
afy collections delete articles --yes --jsonGetting an Aetherfy collection back: afy collections restore-points and restore
A collection that still exists, or one that was deleted, can be restored from a restore
point: the copy Aetherfy took when the collection was deleted, or one of its daily
copies. afy collections restore-points lists them and afy collections restore makes a
new collection from one. The collection the point is a copy of is never changed. What a
restore point is, what comes back and the worked example are on
restoring a collection; the days each plan reaches and the restores a
month allows are on the limits.
afy collections restore-points articles --workspace research
afy collections restore-points --workspace research
afy collections restore-points --collection-id 3f2b0c1e-0c61-4c0e-9b53-2f9f6a7a4d10
afy collections restore day_3f2b0c1e-0c61-4c0e-9b53-2f9f6a7a4d10_2026-10-30 --workspace research --wait
afy collections restore 3f2b0c1e-0c61-4c0e-9b53-2f9f6a7a4d10 --as articles-v2 --jsonafy collections restore-points lists in one of three ways, and exactly one is asked for:
a live collection by its name (its daily copies), the workspace’s deleted collections (no
argument, each as the copy taken at its deletion, with the collection’s id), or one
collection by its id (--collection-id, live or deleted: for a deleted collection, its
deletion copy and the daily copies from before it was deleted). A name together with
--collection-id is refused before anything is sent (exit 2).
Each row shows the id to restore it by, its kind (daily or deletion), when it was taken,
until when it can be restored (a copy taken at a deletion), its points and size, and its
status (ready, backing_up, unavailable or restoring). A daily copy is as of a range
of times, not one moment, because a collection’s shards are copied one after another: a
range is shown where the shards were taken more than a minute apart. The deleted
collections’ list also shows who deleted each one (person, or agent and its id). The
last line says how far back each kind of copy reaches on your plan and what is left of its
restores and restored volume this month.
With --json, restore_points holds each point’s id, kind, collection (id, name,
workspace, deleted), taken_at, points, bytes, regions, status and restore,
a daily copy’s day, taken_from and taken_to, and a deletion copy’s deleted_by
(kind and, for an agent, agent_id) and expires_at (null on a plan with no time limit);
allowance holds recovery_days, daily_days, restores_per_month, restores_left,
restore_bytes_per_month, restore_bytes_left and resets_at.
afy collections restore <restore-point> restores one, by the id the list gives. The id is
sent as given: the CLI never turns a name into one. Without --as the new collection is
called the first free of the collection’s old name and the old name with the point’s date
(<name>-<date>); with --as, a name that a collection or an alias already has in the
workspace is refused with 409 COLLECTION_NAME_TAKEN_FOR_RESTORE and nothing is created.
| Flag | Type | Default | Description |
|---|---|---|---|
--as | string | the old name, or <name>-<date> if that is taken | Name for the restored collection |
--wait | bool | false | Follow the restore to the end (exit 1 if it fails, 4 if still running after 30 minutes) |
--collection-id | string | none | Of restore-points: list the restore points of the collection with this id |
A restore runs in the background, region by region. Without --wait the command prints
the restore and how many of its regions are ready, and returns; with it, the command polls
until the collection is ready. The --json output’s restore holds restore_id,
collection_id (the new collection’s id), name, regions, state, regions_ready and
regions_total.
A restore counts against one allowance of restores per calendar month and of volume restored,
whichever kind of point it is. Past either, Aetherfy refuses with 403 PLAN_LIMIT_EXCEEDED,
whose limit names which (collection_restores_per_month or max_storage_bytes), with the
plan’s number and, in the message, when it resets. A daily copy on a plan with no daily copies
is the same code with limit collection_backup_restore_days; a copy taken at a deletion
past your plan’s window is 410 COLLECTION_BACKUP_EXPIRED; an id that names nothing of
yours is 404 COLLECTION_BACKUP_NOT_FOUND. Only a person’s API key can do this: an agent’s
key is refused. The routes behind the two commands are on restoring a
collection.
Changing an Aetherfy collection’s regions: preview, then confirm
afy collections regions <name> changes the regions a collection’s data is
placed in. A region it adds gets a copy of the collection’s data; a region it
removes has its copy deleted. So the change takes two steps. First the Aetherfy
CLI shows the control plane’s preview, which is built by the same planner the
change runs, so the change does what its preview says. Then it asks
Proceed? [y/N] on stderr.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--regions | strings | none, required | Comma-separated regions to place the collection in | |
--yes | -y | bool | false | Make the change without asking |
--wait | bool | false | Follow the change to its end |
afy collections regions articles --regions us-east-1,eu-central-1Collection 'articles' in workspace 'default': us-east-1 -> us-east-1, eu-central-1
Adds eu-central-1: copies 3 GB of data into it.
Region change 4 of 10 that copy data in the last 30 days.
50 GB of 400 GB copied between regions in the last 30 days; 347 GB left after this change.
Proceed? [y/N]A change that only removes regions copies no data, and the preview says it does
not count toward your plan’s region-change limits. Answering anything but y
or yes changes nothing and exits 1 with Cancelled: collection '<name>' was not changed (under --json, an error document with that message and the code CLI_CANCELLED).
When stdin is not a terminal, nobody can answer the question, so without --yes
the Aetherfy CLI sends nothing and exits 2, before asking: This changes the regions of collection '<name>'; pass --yes to confirm without a prompt. With a
terminal, --json asks on stderr and keeps stdout to one object. A script passes
--yes:
afy collections regions articles --regions us-east-1 --workspace research --yes --wait --jsonA change the control plane would refuse is refused at the preview, and nothing
is sent: the preview’s lines are followed by the refusal’s message and code on
stderr, and the exit code is 1. The refusals, among them
REGION_CHANGE_COUNT_LIMIT_EXCEEDED and REGION_CHANGE_SIZE_LIMIT_EXCEEDED
with the time the next change is allowed, are listed on
/agents/api-workspaces. A change to the regions the
collection is already in changes nothing and exits 0.
The --json object holds collection, preview (the control plane’s preview:
from_regions, to_regions, regions_to_add, regions_to_remove, no_op,
copy_bytes, data_deleted_from and limits), operation_id (null for no
change) and operation, the finished operation under --wait, else null.
Your plan’s Aetherfy region-change limits: afy collections region-limits
afy collections region-limits shows your plan’s limits on region changes, and
how much of them you have used in the rolling window: the region changes that
copied data, and the data they copied. It changes nothing; afy collections regions makes a change, and checks it against these limits. They are the
figures the dashboard’s Usage page shows as REGION CHANGES and DATA COPIED.
afy collections region-limitsRegion changes that copy data, last 30 days
Changes: 2 of 10
Data copied: 8.6 MB of 400 GBOnly a change that adds a region to a collection counts. Dropping a region, or
moving a collection to another workspace, does not. A limit your plan does not
have reads no limit. At a limit, an At the limit: line says when the oldest
counted change leaves the window and frees room.
Its --json output holds region_limits: window_days, count_used,
count_limit, size_used_bytes, size_limit_bytes (a null limit is no
limit) and frees_at (null when nothing is counted).
Renaming an Aetherfy collection: afy collections update
afy collections update <name> renames a collection, changes its description, or
both. The collection stays in its workspace: moving it is afy collections move.
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | none | The collection’s new name |
--description | string | none | The new description; --description "" clears it |
# Rename a collection
afy collections update articles --name articles-v1 --workspace research
# Change its description
afy collections update articles --description "News articles, 2026"A rename changes the name only: the collection’s data, its aliases, its schema and
its regions stay. Code that addresses it by the old name stops finding it. A name
already used by a collection or an alias in the workspace is refused, and so is
renaming the memory SDK’s __threads__ collection. Renaming is for people: an
agent’s key is refused (AUTH_AGENT_KEY_OUT_OF_SCOPE), and neither SDK has it.
Aetherfy payload schemas: afy collections schema
A collection’s payload schema says which fields its points’ payloads carry, and
whether a write that breaks it is let through (off), logged (warn) or refused
(strict). Four commands manage it, all taking the four flags above:
| Command | Does |
|---|---|
afy collections schema get <collection> | Shows the schema, its enforcement mode, its description and its version (etag) |
afy collections schema set <collection> --file <file> | Replaces the schema from a JSON file |
afy collections schema delete <collection> | Deletes the schema; the points are not touched, and writes are no longer checked |
afy collections schema analyze <collection> | Samples the points and suggests a schema; nothing is changed |
The read-edit-set flow
To change a schema, read it to a file, edit the file, and set it from the file:
afy collections schema get articles --save schema.json
# ...edit schema.json...
afy collections schema set articles --file schema.jsonget --save <file> writes {"schema": ..., "enforcement_mode": ..., "description": ..., "etag": ...}. --save names the file. An existing file is kept: without --force (-f) the command
refuses, sends nothing and exits 2 with <file> already exists. Use --force to overwrite., the sentence afy init uses too.
set --file sends the file’s etag as If-Match, so it only replaces the schema
you read:
- If the schema changed since you read it,
setis refused (changed since you read it, exit1) and writes nothing. It never retries without the check. Read the schema again and redo the edit. - The write replaces the whole schema, description included. A file without
descriptionclears the stored one;get --savewrites the description into the file, so the flow keeps it. - A file without an etag sets a first schema only. When the collection already
has one it is refused, naming
get --save, so a hand-written file can never overwrite someone’s schema. Two first schemas set at the same moment both succeed, and the later one stays. enforcement_modeabsent means the server’s default,off.- Unknown keys in the file, a missing file, and a missing or
nullschemaare refused before any request (exit2).
delete asks you to type the collection’s name; --yes (-y) skips the question
and is required without a terminal (refused with exit 2 before asking). Typing
another name cancels with exit 1 and nothing deleted. analyze takes --sample-size N (the server’s
default when omitted): per field it reports how many points carry it, its types
(and an array’s element types) and warnings such as mixed types or rare presence,
and ends with a suggested schema. With --json it returns the full
analysis: presence, types, warnings, samples, element_types for arrays and
nested for objects.
Through an alias, set and delete print the server’s 409 ADDRESSED_AN_ALIAS
sentence and get and analyze its 404 COLLECTION_NOT_FOUND, once each:
name the collection itself.
Moving an Aetherfy collection to another workspace
afy collections move <name> moves a collection to the workspace --to names.
The collection is found in the workspace --workspace chooses, like every
collections command, so --to names only where it goes. A move changes only which
workspace reaches the collection: its regions and its data stay where they are, so
it copies nothing and asks nothing. Each of the regions the collection is placed in
must be one of the target workspace’s. The collection’s aliases move with it. A
workspace that already has a collection or an alias of that name (and a collection
whose alias would clash there) is refused before anything starts. The memory SDK’s
__threads__ collection is never moved.
| Flag | Type | Default | Description |
|---|---|---|---|
--to | string | none, required | The workspace to move the collection to. Empty is refused |
--wait | bool | false | Follow the move to its end |
afy collections move articles --workspace default --to research
afy collections move articles --workspace default --to research --wait --jsonThe --json object holds collection, to, no_op, regions, operation_id
and operation.
Protecting an Aetherfy collection from agents
afy collections protect <name> protects a collection, and afy collections unprotect <name> turns that off. On a protected collection no agent’s API key may
remove data from it, whatever its access level: delete the collection, delete
points, vectors or payload fields (by id or by filter), or delete or repoint an
alias that points at it. Adding and updating points stays allowed, and so does
overwriting an existing point. Your own key can still do all of it. Nothing is
deleted or changed by protecting. See
agent access.
Protecting narrows what agents can do and asks nothing. Unprotecting widens it, so
it asks Proceed? [y/N] and says what it lets agents do: Unprotecting '<name>' lets agents with read and write access delete its points, and agents with full access delete the collection. Answering no exits 1 with Cancelled: collection '<name>' was not changed and changes nothing. --yes skips the question; without a
terminal it is required, and the command exits 2 before sending anything
(This turns protection off for collection '<name>'; pass --yes to confirm without a prompt.). With a terminal, --json asks on stderr and keeps stdout to one object.
afy collections protect support-kb --workspace research
afy collections unprotect support-kb --workspace research --yes --jsonThe --json object holds collection, protected and no_op.
Both commands return once the control plane accepts the change, which then
runs in the background. --wait follows it, as afy start --wait follows a
start: exit 0 when it succeeds, 1 when it fails, with the failure’s message,
and 4 when it is still running after 30 minutes. It keeps running then, and
afy collections get <name> shows it while it runs and the result once it
finishes.
Aetherfy payload indexes: afy index create waits until the index is built
afy index create <collection> <field> creates a payload index on one field
and exits 0 only once the index is built, so a filter or an ordered scroll on
the field works as soon as it returns.
| Flag | Type | Default | Description |
|---|---|---|---|
--type | string | none, required | keyword, integer, float, bool, geo, datetime, uuid, text, or a JSON object for a parameterised index |
--timeout | number | 600 | Seconds to wait for the build before giving up |
The default wait is ten minutes; these two commands wait the same way:
afy index create articles thread_id --type keyword
afy index create articles thread_id --type keyword --timeout 600afy index create articles ts --type integer --timeout 300 --json
afy index create articles body --type '{"type":"text","tokenizer":"word","lowercase":true}'This is the Aetherfy SDKs’ create_field_index behaviour, step for step:
| Step | What happens |
|---|---|
| The server holds the create | Aetherfy waits a while for the build before answering |
completed | The index is built; the command exits 0 |
acknowledged | The build outlived that wait and carries on; the command sends the same create again, which waits for the running build |
An acknowledged that came back at once | The server did not hold it, so the next create waits first, a little longer each time |
| Any other answer | An error, exit 1; the index is not confirmed built |
The --timeout passes | Exit 1 with “is still building”; the build carries on, and running the same command again waits for it |
A --timeout that is not a number of seconds above 0 is refused before any
request, naming the value, with exit code 2.
afy index delete <collection> <field> drops the index on one field in a
single request, allowed as long as a create, because Aetherfy may hold a
delete the same way. Dropping an index the field does not have succeeds; a
collection that does not exist is an error.
afy index delete articles thread_idReading Aetherfy points: count, get, and search
--filter takes a filter as a JSON object, in the shape the SDKs send (see
/vectors/filtering), on every points command that has
it. The CLI sends the object as you wrote it; the Aetherfy vectors API checks
every key of it. A key the filter does not have, such as shuold for should,
is refused with INVALID_FILTER: the message names the key, where it sits in
the filter and the nearest valid key, and the command exits 1 with the API’s
code and message, as for any refused request. Nothing is counted, returned or
deleted on a refused filter.
afy points count <collection> counts the points exactly. Without --json it
prints the bare number, so $(afy points count articles) is the count.
afy points count articles
afy points count articles --filter '{"must":[{"key":"lang","match":{"value":"en"}}]}' --jsonafy points get <collection> <id>... reads points by id, with their payloads
and without their vectors. An id made only of digits is sent as a number,
anything else as a string, such as a UUID. An id that does not exist is left
out of the answer rather than reported.
afy points get articles 17 42 --jsonafy points search <collection> returns the points nearest to a vector.
| Flag | Type | Default | Description |
|---|---|---|---|
--vector | string | none, required | A JSON array of numbers, or @path to read one from a file |
--limit | int | 10 | How many points to return |
--filter | string | none | Only return points this filter matches |
afy points search articles --vector '[0.12, -0.03, 0.88]' --limit 5
afy points search articles --vector @query.json --jsonIn --json output each entry of points carries id and payload, and a
search hit carries score as well.
Browsing Aetherfy points: afy points list pages through a collection
afy points list <collection> pages through a collection’s points in id order,
with their payloads. It is the SDKs’ scroll.
| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 10 | How many points a page holds, at most 1000 |
--offset | string | none | The id to start at: the previous page’s next_page_offset |
--filter | string | none | Only list the points this filter matches |
--with-vectors | bool | false | Include each point’s vector |
1000 is the most the Aetherfy vectors API returns in one read; a --limit
outside 1 to 1000 is refused before any request, with exit code 2. When there
are more points, the page ends with the id the next one starts at. Pass it as
--offset to read the next page, with the same --filter:
afy points list articles
afy points list articles --offset 11Without --json each row is a point’s id and the start of its payload, your
own keys first, and the page ends with More points: pass --offset 11 for the next page. when there is one. With --json the object holds points (each
with id, payload, and vector under --with-vectors) and
next_page_offset, which is null on the last page. A script passes it back
until it is null:
afy points list articles --limit 100 --json > page.json
afy points list articles --limit 100 --offset "$(jq -r .next_page_offset page.json)" --jsonWriting Aetherfy points: afy points upsert adds or replaces by id
afy points upsert <collection> writes the points --points gives: one point
object or a JSON array of them, inline or @path to read them from a file. A
point is the vectors API’s own shape: an id (a whole number or a UUID), a
vector, and an optional payload object. A point whose id already exists is
replaced, vector and payload, without a question, as the SDKs’ upsert
does.
| Flag | Type | Default | Description |
|---|---|---|---|
--points | string | none | The points: one point object or a JSON array of them, or @path to them; required |
afy points upsert articles --points '{"id": 1, "vector": [0.12, -0.03, 0.88], "payload": {"lang": "en"}}'
afy points upsert articles --points @points.json --jsonUpserted 1 point(s) into collection 'articles'.With --json the object holds collection and upserted, the number of
points written. A missing --points, input that is not JSON, an empty array,
or a point without an id or a vector is refused before any request, with
exit code 2. Every other rule (the vector’s size, reserved __aetherfy_
payload keys, the size caps) is the Aetherfy vectors API’s, and its error is
printed as it came, with exit code 1.
The points are sent in order, in requests of at most 10 000 points or 24 MiB,
the way the SDKs split an upsert (see /vectors/limits). Each
request waits up to 100 seconds, longer than the vectors API lets any request
run, so the API always answers or ends a request before the CLI gives up. If a
request fails, the error says how many points were written before it
(written in the --json error object). When the failed request’s own outcome
cannot be known, the error also says how many points it held (unconfirmed):
they may or may not have been written. That is the case when the connection
was lost before an answer, when the server failed, and when
the server refused a request larger than one 12 MB chunk, because the vectors
API writes an upsert in chunks as it reads it and a refusal leaves the chunks
already written in place. A refused request no larger than one 12 MB chunk
wrote nothing. Re-running the same upsert is safe in every case: points are
replaced by id.
Points written with your API key read back with __aetherfy_agent_id null:
a person’s write, not an agent’s.
Deleting Aetherfy points: afy points delete counts first
afy points delete <collection> <id>... deletes points by id, or with
--filter instead of ids, every point a filter matches. Give one or the other:
both, or neither, is refused before any request, with exit code 2.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--filter | string | none | Delete the points this filter matches, instead of ids | |
--yes | -y | bool | false | Delete without asking |
Before deleting anything, the Aetherfy CLI counts what will go and prints the
count on stderr: by id, the ids that exist (only those are deleted); by
filter, the points the filter matches now, the same count
afy points count <collection> --filter gives. Then it asks you to type the
collection’s name; typing anything else deletes nothing and exits 2. When
nothing matches, nothing is deleted and nothing is asked.
afy points delete articles 17 422 point(s) in collection 'articles' will be deleted.
Type the collection name to confirm: articles
Deleted 2 point(s) from collection 'articles'.When stdin is not a terminal, nobody can answer the question, so without
--yes the Aetherfy CLI deletes nothing, sends nothing and exits 2, before
asking: This deletes points from collection '<name>'; pass --yes to confirm without a prompt. Typing another name cancels: exit 1 with Cancelled: the name typed did not match. A script passes --yes; with --json the object holds collection and
deleted, the count shown before the delete. A filter delete removes what
matches when it runs, so a point written in between that matches is deleted
too and is not in that count:
afy points delete articles --filter '{"must":[{"key":"lang","match":{"value":"de"}}]}' --yes --jsonA filter with a key the API does not know is refused at the count that comes first, with
INVALID_FILTER and exit code 1, before any question is asked: nothing is
deleted.
An empty filter is refused, with exit code 2: {}, or a filter whose clauses
are all empty, matches every point, and deleting every point is
afy collections delete <name>.
afy points delete articles --filter '{}' --yesError: not deleting: an empty --filter matches every point in 'articles'. To delete the whole collection, run afy collections delete articles.Aetherfy vector command errors and exit codes
| Code | When |
|---|---|
| 0 | Success |
| 1 | The request failed: the Aetherfy vectors API or the control plane refused it (a regions change refused at its preview included, and a --filter with a key the API does not know, INVALID_FILTER), it got no answer, an index was still building at the deadline, or a change or restore --wait followed failed |
| 2 | The input was refused before any request: a deleted collection name that matches none or two, a bad --size, --distance, --timeout, --vector, --points, --filter, --limit, --type or --api-region, a missing --regions or --to, a delete or regions change nobody confirmed, a points delete given both ids and --filter, neither, or an empty filter, or a command line that does not parse (an unknown flag, a value of the wrong type, the wrong number of arguments) |
| 3 | Not logged in |
| 4 | A change or restore --wait followed was still running after 30 minutes |
Nothing goes to stdout on a failure, except what was printed before it without
--json: the preview of a regions change the control plane refuses, or the line
--wait prints before following a change that then fails. On stderr, the Aetherfy vectors API’s or the control
plane’s own status, code and message are copied through unchanged. With --json stderr
holds one object, for every failure except a command line that does not
parse, which is a plain Error: line because parsing stopped before --json
was necessarily read:
{"error": {"status": 404, "code": "NOT_FOUND", "message": "Collection 'articles' not found"}}Without --json it is one line, Error: Collection 'articles' not found (NOT_FOUND).
A refused filter key adds field (where the key sits in the request), key and, when there is a near match, suggestion, each as the API sent it:
{"error": {"status": 400, "code": "INVALID_FILTER", "message": "Unrecognised filter key 'shuold' at filter.shuold. Did you mean 'should'?", "field": "filter.shuold", "key": "shuold", "suggestion": "should"}}A failure that got no answer from the API has no status or code. The codes
themselves are listed on /vectors/errors.