Vectorize V1 is an open-beta product, and Vectorize V2 is a re-architectured system that will soon go beta and eventually GA (at which point we will deprecate Vectorize v1).

Vectorize V2 is essentially a different product. V2 operations can only work on a v2 index (created using the use-v2 flag) and the same applies for V1. However, we cannot create a v2 index if a v1 index of the same name exists and vice versa.

Updated the changeset patch to minor, and made the v2 option description in the commands more descriptive. @petebacondarwin I hope that would be sufficient.

What does v2 mean when it comes to indexes?
What would happen if test-index was not v2?

If we try a v2 operation (say get index) on a v1 index, the wrangler client would receive a 403 response from Vectorize. Same goes if we try a v1 operation on a v2 index.

What would be the error message. Will it be clear to the user what went wrong and what to do to fix it?
Also what is the roll off plan for deprecating and removing v1?

For example, for how long will you support use-v2 as a command line flag?
In general we are moving towards feature flagging things in Wrangler with the experimental/x prefix. So in this case it would be

wrangler vectorize get test-index --experimental-v2

or

wrangler vectorize get test-index --x-v2

And for stuff you are removing prefixing with legacy/deprecated. For example:

wrangler vectorize get test-index --legacy-v1

or

wrangler vectorize get test-index --deprecated-v1

The error message in the apiv4 response format would be like Index: "${index_name}" with version "${index_version}" called with api version "${operation_version}" along with a 403 response.

I would let Yevgen address the deprecation plan.

cc @sejoker

For example, for how long will you support use-v2 as a command line flag? In general we are moving towards feature flagging things in Wrangler with the experimental/x prefix. So in this case it would be

wrangler vectorize get test-index --experimental-v2

or

wrangler vectorize get test-index --x-v2

And for stuff you are removing prefixing with legacy/deprecated. For example:

wrangler vectorize get test-index --legacy-v1

or

wrangler vectorize get test-index --deprecated-v1

@petebacondarwin the plan to start with private beta this month, once we will be confident to open it up for public beta sometime in August we will stop allowing V1 index creation and V2 only will be used for new indexes.

I like the idea of using --deprecated-v1 for dealing with existing V1 indexes once V2 goes to public beta.

We discussed this within our team, and decided to with an --experimental-v2 flag with a default value of false until we put v1 indexes on the deprecation path. At that time we will switch to --deprecated-v1.

Made the change to update the commands and the related docs.

We discussed this within our team, and decided to with an --experimental-v2 flag with a default value of false until we put v1 indexes on the deprecation path. At that time we will switch to --deprecated-v1.

Made the change to update the commands and the related docs.

This is not what I see in the current code for this PR.
I see that there is no --experimental-v2 flag here only the --deprecated-v1 flag, which defaults to false.

I would assume that for the private beta the default needs to switch to true and the --experimental-v2 flag needs to be implemented?

Also, could I call out that it would be much nicer for the user if these commands inferred the version of the index from its type (via a REST request) rather than requiring the user to keep track of which version they are using. The only place one really needs the v1/v2 flag is at index creation time, no?