Skip to Content
CLIafy collections, index & points
Raw

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).

CommandPurpose
afy collections listList 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-limitsShow 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.

FlagTypeDefaultDescription
--jsonboolfalsePrint one JSON object with stable field names. It is the root flag, accepted on every command
--workspacestringthe account’s only workspace; asked when there are severalWorkspace the collection names belong to. Required without a terminal, and with --json, when the account has several
--vectors-urlstringsee belowAetherfy vectors API endpoint
--api-regionstringAETHERFY_VECTORS_API_REGIONAPI 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:

  1. --vectors-url, when given.
  2. 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.
  3. --api-region, else AETHERFY_VECTORS_API_REGION. The region is turned into a URL by asking GET /api/v1/regions on https://vectors.aetherfy.com.
  4. 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 --workspace is required: the command exits 2 and sends nothing, naming the workspaces to choose from.
  • No environment variable sets it. AETHERFY_WORKSPACE is not read, and an empty --workspace "" is refused (exit 2). A --workspace or --to value 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 --json

The 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 --json

Creating and deleting Aetherfy collections

afy collections create <name> creates a collection for vectors of one size, compared with one distance.

FlagTypeDefaultDescription
--sizeintnone, requiredVector size in dimensions, above 0
--distancestringnone, requiredcosine, dot, euclid or manhattan
--regionsstringsevery region your plan or workspace coversComma-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 --json

The --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.

FlagShortTypeDefaultDescription
--yes-yboolfalseDelete 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 --json

Getting 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 --json

afy 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.

FlagTypeDefaultDescription
--asstringthe old name, or <name>-<date> if that is takenName for the restored collection
--waitboolfalseFollow the restore to the end (exit 1 if it fails, 4 if still running after 30 minutes)
--collection-idstringnoneOf 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.

FlagShortTypeDefaultDescription
--regionsstringsnone, requiredComma-separated regions to place the collection in
--yes-yboolfalseMake the change without asking
--waitboolfalseFollow the change to its end
afy collections regions articles --regions us-east-1,eu-central-1
Collection '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 --json

A 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-limits
Region changes that copy data, last 30 days Changes: 2 of 10 Data copied: 8.6 MB of 400 GB

Only 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.

FlagTypeDefaultDescription
--namestringnoneThe collection’s new name
--descriptionstringnoneThe 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:

CommandDoes
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.json

get --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, set is refused (changed since you read it, exit 1) 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 description clears the stored one; get --save writes 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_mode absent means the server’s default, off.
  • Unknown keys in the file, a missing file, and a missing or null schema are refused before any request (exit 2).

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.

FlagTypeDefaultDescription
--tostringnone, requiredThe workspace to move the collection to. Empty is refused
--waitboolfalseFollow the move to its end
afy collections move articles --workspace default --to research afy collections move articles --workspace default --to research --wait --json

The --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 --json

The --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.

FlagTypeDefaultDescription
--typestringnone, requiredkeyword, integer, float, bool, geo, datetime, uuid, text, or a JSON object for a parameterised index
--timeoutnumber600Seconds 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 600
afy 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:

StepWhat happens
The server holds the createAetherfy waits a while for the build before answering
completedThe index is built; the command exits 0
acknowledgedThe 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 onceThe server did not hold it, so the next create waits first, a little longer each time
Any other answerAn error, exit 1; the index is not confirmed built
The --timeout passesExit 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_id

--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"}}]}' --json

afy 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 --json

afy points search <collection> returns the points nearest to a vector.

FlagTypeDefaultDescription
--vectorstringnone, requiredA JSON array of numbers, or @path to read one from a file
--limitint10How many points to return
--filterstringnoneOnly 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 --json

In --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.

FlagTypeDefaultDescription
--limitint10How many points a page holds, at most 1000
--offsetstringnoneThe id to start at: the previous page’s next_page_offset
--filterstringnoneOnly list the points this filter matches
--with-vectorsboolfalseInclude 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 11

Without --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)" --json

Writing 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.

FlagTypeDefaultDescription
--pointsstringnoneThe 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 --json
Upserted 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.

FlagShortTypeDefaultDescription
--filterstringnoneDelete the points this filter matches, instead of ids
--yes-yboolfalseDelete 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 42
2 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 --json

A 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 '{}' --yes
Error: 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

CodeWhen
0Success
1The 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
2The 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)
3Not logged in
4A 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.

Last updated on