Re: [EXTERNAL] Re: [DISCUSS] Adding experimental vtables and rules around them

[Josh McKenzie]

> I like it as it makes this apart of its name, but is sad that we must break 
> compatibility once we mark it stable (as we move the keyspace).  
+1 to this exact set of sentiments. The next logical question to me is "should 
we alias the old system_experimental* table name to the new stable table name 
for vtables once they graduate to support backwards compatibility", but I think 
I fall on the "no" side there.

On Fri, May 31, 2024, at 5:15 PM, J. D. Jordan wrote:
> 
> We have already agreed in the past that having experimental features, behind 
> feature flags, in stable releases is a good thing for keeping those features 
> up to date, for getting feedback from end users, and many others.
> The question here is about how we ensure that end users are aware something 
> is experimental, because the person who installed C* and enabled the feature 
> flag is likely not the same person who is using the feature.
> 
>> On May 31, 2024, at 3:23 PM, German Eichberger via dev 
>>  wrote:
>> 
>> Hi,
>> 
>> To sum where everyone is coming from: We would like to have features in a 
>> stable version of Cassandra which are experimental and are subject to 
>> non-backward compatible change. This indicates to me that the feature is not 
>> finished and should likely not be included in a stable release.  What 
>> benefit are we looking for by including it into a stable release as opposed 
>> to rolling it to the next release.
>> 
>> Thanks,
>> German
>> 
>> 
>> *From:* Maxim Muzafarov 
>> *Sent:* Wednesday, May 29, 2024 1:09 PM
>> *To:* dev@cassandra.apache.org 
>> *Subject:* [EXTERNAL] Re: [DISCUSS] Adding experimental vtables and rules 
>> around them
>>  
>> Hello everyone,
>> 
>> I like the idea of highlighting some of the experimental virtual
>> tables whose model might be changed in future releases.
>> 
>> As another option, we could add an @Experimetal annotation (or another
>> name) and a configuration parameter
>> experimental_virtula_tables_enabled (default is false). This, in turn,
>> means if a virtual table is experimental, it won't be registered in a
>> virtual keyspace unless the corresponding configuration parameter is
>> enabled. This also means that a user must implicitly enable an
>> experimental API, and prevent us from spamming the log with warnings.
>> All of this does not preclude us from specifying the experimental
>> state of some virtual tables in the documentation.
>> 
>> On Wed, 29 May 2024 at 21:18, Abe Ratnofsky  wrote:
>> >
>> > I agree that ClientWarning is the best way to indicate the risk of using 
>> > an experimental feature directly to the user. Presenting information in 
>> > the client application's logs directly means that the person who wrote the 
>> > query is most likely to see the warning, rather than an operator who sees 
>> > cluster logs.
>> >
>> > I don't think it's necessary to attach a ClientWarning to every single 
>> > client response; a ClientWarning analog to NoSpamLogger would be useful 
>> > for this ("warn a client at most once per day").
>> >
>> > This would also be useful for warning on usage of deprecated features.
>> >
>> > > On May 29, 2024, at 3:01 PM, David Capwell  wrote:
>> > >
>> > > We agreed a long time ago that all new features are disabled by default, 
>> > > but I wanted to try to flesh out what we “should” do with something that 
>> > > might still be experimental and subject to breaking changes; I would 
>> > > prefer we keep this thread specific to vtables as the UX is different 
>> > > for different types of things…
>> > >
>> > > So, lets say we are adding a set of vtables but we are not 100% sure 
>> > > what the schema should be and we learn after the release that changes 
>> > > should be made, but that would end up breaking the table… we currently 
>> > > define everything as “don’t break this” so if we publish a table that 
>> > > isn’t 100% baked we are kinda stuck with it for a very very long time… I 
>> > > would like to define a way to expose vtables that are subject to change 
>> > > (breaking schema changes) across different release and rules around them 
>> > > (only in minor?  Maybe even in patch?).
>> > >
>> > > Lets try to use a concrete example so everyone is on the same page.
>> > >
>> > > Accord is disabled by default (it is a new feature), so the vtables to 
&

Re: [EXTERNAL] Re: [DISCUSS] Adding experimental vtables and rules around them

[J. D. Jordan]

We have already agreed in the past that having experimental features, behind 
feature flags, in stable releases is a good thing for keeping those features up 
to date, for getting feedback from end users, and many others.
The question here is about how we ensure that end users are aware something is 
experimental, because the person who installed C* and enabled the feature flag 
is likely not the same person who is using the feature.

> On May 31, 2024, at 3:23 PM, German Eichberger via dev 
>  wrote:
> 
> 
> Hi,
> 
> To sum where everyone is coming from: We would like to have features in a 
> stable version of Cassandra which are experimental and are subject to 
> non-backward compatible change. This indicates to me that the feature is not 
> finished and should likely not be included in a stable release.  What benefit 
> are we looking for by including it into a stable release as opposed to 
> rolling it to the next release.
> 
> Thanks,
> German
> From: Maxim Muzafarov 
> Sent: Wednesday, May 29, 2024 1:09 PM
> To: dev@cassandra.apache.org 
> Subject: [EXTERNAL] Re: [DISCUSS] Adding experimental vtables and rules 
> around them
>  
> Hello everyone,
> 
> I like the idea of highlighting some of the experimental virtual
> tables whose model might be changed in future releases.
> 
> As another option, we could add an @Experimetal annotation (or another
> name) and a configuration parameter
> experimental_virtula_tables_enabled (default is false). This, in turn,
> means if a virtual table is experimental, it won't be registered in a
> virtual keyspace unless the corresponding configuration parameter is
> enabled. This also means that a user must implicitly enable an
> experimental API, and prevent us from spamming the log with warnings.
> All of this does not preclude us from specifying the experimental
> state of some virtual tables in the documentation.
> 
> On Wed, 29 May 2024 at 21:18, Abe Ratnofsky  wrote:
> >
> > I agree that ClientWarning is the best way to indicate the risk of using an 
> > experimental feature directly to the user. Presenting information in the 
> > client application's logs directly means that the person who wrote the 
> > query is most likely to see the warning, rather than an operator who sees 
> > cluster logs.
> >
> > I don't think it's necessary to attach a ClientWarning to every single 
> > client response; a ClientWarning analog to NoSpamLogger would be useful for 
> > this ("warn a client at most once per day").
> >
> > This would also be useful for warning on usage of deprecated features.
> >
> > > On May 29, 2024, at 3:01 PM, David Capwell  wrote:
> > >
> > > We agreed a long time ago that all new features are disabled by default, 
> > > but I wanted to try to flesh out what we “should” do with something that 
> > > might still be experimental and subject to breaking changes; I would 
> > > prefer we keep this thread specific to vtables as the UX is different for 
> > > different types of things…
> > >
> > > So, lets say we are adding a set of vtables but we are not 100% sure what 
> > > the schema should be and we learn after the release that changes should 
> > > be made, but that would end up breaking the table… we currently define 
> > > everything as “don’t break this” so if we publish a table that isn’t 100% 
> > > baked we are kinda stuck with it for a very very long time… I would like 
> > > to define a way to expose vtables that are subject to change (breaking 
> > > schema changes) across different release and rules around them (only in 
> > > minor?  Maybe even in patch?).
> > >
> > > Lets try to use a concrete example so everyone is on the same page.
> > >
> > > Accord is disabled by default (it is a new feature), so the vtables to 
> > > expose internals would be expected to be undefined and not present on the 
> > > instance.
> > >
> > > When accord is enabled (accord.enabled = true) we add a set of vtables:
> > >
> > > Epochs - shows what epochs are known to accord
> > > Cache - shows how the internal caches are performing
> > > Etc.
> > >
> > > Using epochs as an example it currently only shows a single column: the 
> > > long epoch
> > >
> > > CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint PRIMARY KEY);
> > >
> > > Lets say we find that this table isn’t enough and we really need to scope 
> > > it to each of the “stores” (threads for processing accord tasks)
> > >
> > > CREATE VIRTUAL TABLE s

Re: [EXTERNAL] Re: [DISCUSS] Adding experimental vtables and rules around them

[German Eichberger via dev]

Hi,

To sum where everyone is coming from: We would like to have features in a 
stable version of Cassandra which are experimental and are subject to 
non-backward compatible change. This indicates to me that the feature is not 
finished and should likely not be included in a stable release.  What benefit 
are we looking for by including it into a stable release as opposed to rolling 
it to the next release.

Thanks,
German

From: Maxim Muzafarov 
Sent: Wednesday, May 29, 2024 1:09 PM
To: dev@cassandra.apache.org 
Subject: [EXTERNAL] Re: [DISCUSS] Adding experimental vtables and rules around 
them

Hello everyone,

I like the idea of highlighting some of the experimental virtual
tables whose model might be changed in future releases.

As another option, we could add an @Experimetal annotation (or another
name) and a configuration parameter
experimental_virtula_tables_enabled (default is false). This, in turn,
means if a virtual table is experimental, it won't be registered in a
virtual keyspace unless the corresponding configuration parameter is
enabled. This also means that a user must implicitly enable an
experimental API, and prevent us from spamming the log with warnings.
All of this does not preclude us from specifying the experimental
state of some virtual tables in the documentation.

On Wed, 29 May 2024 at 21:18, Abe Ratnofsky  wrote:
>
> I agree that ClientWarning is the best way to indicate the risk of using an 
> experimental feature directly to the user. Presenting information in the 
> client application's logs directly means that the person who wrote the query 
> is most likely to see the warning, rather than an operator who sees cluster 
> logs.
>
> I don't think it's necessary to attach a ClientWarning to every single client 
> response; a ClientWarning analog to NoSpamLogger would be useful for this 
> ("warn a client at most once per day").
>
> This would also be useful for warning on usage of deprecated features.
>
> > On May 29, 2024, at 3:01 PM, David Capwell  wrote:
> >
> > We agreed a long time ago that all new features are disabled by default, 
> > but I wanted to try to flesh out what we “should” do with something that 
> > might still be experimental and subject to breaking changes; I would prefer 
> > we keep this thread specific to vtables as the UX is different for 
> > different types of things…
> >
> > So, lets say we are adding a set of vtables but we are not 100% sure what 
> > the schema should be and we learn after the release that changes should be 
> > made, but that would end up breaking the table… we currently define 
> > everything as “don’t break this” so if we publish a table that isn’t 100% 
> > baked we are kinda stuck with it for a very very long time… I would like to 
> > define a way to expose vtables that are subject to change (breaking schema 
> > changes) across different release and rules around them (only in minor?  
> > Maybe even in patch?).
> >
> > Lets try to use a concrete example so everyone is on the same page.
> >
> > Accord is disabled by default (it is a new feature), so the vtables to 
> > expose internals would be expected to be undefined and not present on the 
> > instance.
> >
> > When accord is enabled (accord.enabled = true) we add a set of vtables:
> >
> > Epochs - shows what epochs are known to accord
> > Cache - shows how the internal caches are performing
> > Etc.
> >
> > Using epochs as an example it currently only shows a single column: the 
> > long epoch
> >
> > CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint PRIMARY KEY);
> >
> > Lets say we find that this table isn’t enough and we really need to scope 
> > it to each of the “stores” (threads for processing accord tasks)
> >
> > CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint, store_id int, 
> > PRIMARY KEY (epoch, store_id));
> >
> > In this example the table changed the schema in a way that could break 
> > users, so this normally is not allowed.
> >
> > Since we don’t really have a way to define something experimental other 
> > than NEWS.txt, we kinda get stuck with this table and are forced to make 
> > new versions and maintain them for a long time (in this example we would 
> > have epochs and epochs_v2)… it would be nice if we could define a way to 
> > express that tables are free to be changed (modified or even deleted) and 
> > the life cycle for them….
> >
> > I propose that we allow such a case and make changes to the UX (as best as 
> > we can) to warn about this:
> >
> > 1) update NEWS.txt to denote that the feature is experimental
> > 2) when you access an experimental table you get a ClientWarning stating 
> > that this is free to change
> > 3) the tables comments starts with “[EXPERIMENTAL]”
> >
> > What do others think?
> >
> >
>

Re: [DISCUSS] Adding experimental vtables and rules around them

[Caleb Rackliffe]

The two-part proposal of 1.) table-level self-identification of
experimental status and 2.) a global config flag that determines what to do
when querying those might work. I guess the only thing you can't do there
is ignore warnings from a specific experimental table, since that's
controlled in code and not in configuration? You'd probably have to do that
as a custom argument in the native protocol, similar to the client
instructions for what to do on overload.

On Wed, May 29, 2024 at 6:11 PM David Capwell  wrote:

> As another option, we could add an @Experimetal annotation (or another name)
> and a configuration parameter experimental_virtula_tables_enabled
>
>
> Since these are tables we have TableProps so we could always store an
> experimental = true there and if Config.experimental_virtula_tables_enabled
> == false we just skip those tables when we load them.
>
> That way authors would just do the following…
>
> CreateTableStatement.parse(query, keyspace)
>.comment(comment)
>.kind(TableMetadata.Kind.VIRTUAL)
>.experimental(true)
>.build();
>
> And VirtualKeyspace would skip it when 
> Config.experimental_virtula_tables_enabled
> == false
>
> This feels very similar to the JDK… some features require you to opt into
> experimental things twice…
>
> What about putting such a table to system_experimental keyspace?
>
>
> I like it as it makes this apart of its name, but is sad that we must
> break compatibility once we mark it stable (as we move the keyspace).
>
>
> On May 29, 2024, at 1:23 PM, Štefan Miklošovič <
> stefan.mikloso...@gmail.com> wrote:
>
> I think that 2) (client warning on accessing vtable) is pretty obtrusive /
> irritating, that means that every single time I would e.g. SELECT from such
> a table, it would emit a warning to a client / cqlsh? I do not think that
> is necessary.
>
> What about putting such a table to system_experimental keyspace? Then it
> would be about deciding when it is not considered experimental anymore and
> once that happens, we just move it to the appropriate keyspace. I think
> that it is better if users (rather admins) execute a query against
> system_experimental.accord_epochs so they immediately know what they access
> (something experimental) rather than being constantly reminded about that
> by a client warning.
>
> Maxim's idea about "experimental_virtual_tables_enabled" property is also
> viable. However, I can't help it but that somehow reminds me a property for
> a guardrail. Just a thought. I do not see yet how we could leverage it,
> just saying how I perceive it.
>
> On Wed, May 29, 2024 at 9:02 PM David Capwell  wrote:
>
>> We agreed a long time ago that all new features are disabled by default,
>> but I wanted to try to flesh out what we “should” do with something that
>> might still be experimental and subject to breaking changes; I would prefer
>> we keep this thread specific to vtables as the UX is different for
>> different types of things…
>>
>> So, lets say we are adding a set of vtables but we are not 100% sure what
>> the schema should be and we learn after the release that changes should be
>> made, but that would end up breaking the table… we currently define
>> everything as “don’t break this” so if we publish a table that isn’t 100%
>> baked we are kinda stuck with it for a very very long time… I would like to
>> define a way to expose vtables that are subject to change (breaking schema
>> changes) across different release and rules around them (only in minor?
>> Maybe even in patch?).
>>
>> Lets try to use a concrete example so everyone is on the same page.
>>
>> Accord is disabled by default (it is a new feature), so the vtables to
>> expose internals would be expected to be undefined and not present on the
>> instance.
>>
>> When accord is enabled (accord.enabled = true) we add a set of vtables:
>>
>> Epochs - shows what epochs are known to accord
>> Cache - shows how the internal caches are performing
>> Etc.
>>
>> Using epochs as an example it currently only shows a single column: the
>> long epoch
>>
>> CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint PRIMARY KEY);
>>
>> Lets say we find that this table isn’t enough and we really need to scope
>> it to each of the “stores” (threads for processing accord tasks)
>>
>> CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint, store_id int,
>> PRIMARY KEY (epoch, store_id));
>>
>> In this example the table changed the schema in a way that could break
>> users, so this normally is not allowed.
>>
>> Since we don’t really have a way to define something experimental other
>> than NEWS.txt, we kinda get stuck with this table and are forced to make
>> new versions and maintain them for a long time (in this example we would
>> have epochs and epochs_v2)… it would be nice if we could define a way to
>> express that tables are free to be changed (modified or even deleted) and

Re: [DISCUSS] Adding experimental vtables and rules around them

[David Capwell]

> As another option, we could add an @Experimetal annotation (or another name) 
> and a configuration parameter experimental_virtula_tables_enabled

Since these are tables we have TableProps so we could always store an 
experimental = true there and if Config.experimental_virtula_tables_enabled == 
false we just skip those tables when we load them.

That way authors would just do the following…

CreateTableStatement.parse(query, keyspace)
   .comment(comment)
   .kind(TableMetadata.Kind.VIRTUAL)
   .experimental(true)
   .build();
And VirtualKeyspace would skip it when 
Config.experimental_virtula_tables_enabled == false

This feels very similar to the JDK… some features require you to opt into 
experimental things twice… 

> What about putting such a table to system_experimental keyspace?

I like it as it makes this apart of its name, but is sad that we must break 
compatibility once we mark it stable (as we move the keyspace).  


> On May 29, 2024, at 1:23 PM, Štefan Miklošovič  
> wrote:
> 
> I think that 2) (client warning on accessing vtable) is pretty obtrusive / 
> irritating, that means that every single time I would e.g. SELECT from such a 
> table, it would emit a warning to a client / cqlsh? I do not think that is 
> necessary.
> 
> What about putting such a table to system_experimental keyspace? Then it 
> would be about deciding when it is not considered experimental anymore and 
> once that happens, we just move it to the appropriate keyspace. I think that 
> it is better if users (rather admins) execute a query against 
> system_experimental.accord_epochs so they immediately know what they access 
> (something experimental) rather than being constantly reminded about that by 
> a client warning.
> 
> Maxim's idea about "experimental_virtual_tables_enabled" property is also 
> viable. However, I can't help it but that somehow reminds me a property for a 
> guardrail. Just a thought. I do not see yet how we could leverage it, just 
> saying how I perceive it. 
> 
> On Wed, May 29, 2024 at 9:02 PM David Capwell  > wrote:
>> We agreed a long time ago that all new features are disabled by default, but 
>> I wanted to try to flesh out what we “should” do with something that might 
>> still be experimental and subject to breaking changes; I would prefer we 
>> keep this thread specific to vtables as the UX is different for different 
>> types of things…
>> 
>> So, lets say we are adding a set of vtables but we are not 100% sure what 
>> the schema should be and we learn after the release that changes should be 
>> made, but that would end up breaking the table… we currently define 
>> everything as “don’t break this” so if we publish a table that isn’t 100% 
>> baked we are kinda stuck with it for a very very long time… I would like to 
>> define a way to expose vtables that are subject to change (breaking schema 
>> changes) across different release and rules around them (only in minor?  
>> Maybe even in patch?).
>> 
>> Lets try to use a concrete example so everyone is on the same page.
>> 
>> Accord is disabled by default (it is a new feature), so the vtables to 
>> expose internals would be expected to be undefined and not present on the 
>> instance.
>> 
>> When accord is enabled (accord.enabled = true) we add a set of vtables:
>> 
>> Epochs - shows what epochs are known to accord
>> Cache - shows how the internal caches are performing
>> Etc.
>> 
>> Using epochs as an example it currently only shows a single column: the long 
>> epoch
>> 
>> CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint PRIMARY KEY);
>> 
>> Lets say we find that this table isn’t enough and we really need to scope it 
>> to each of the “stores” (threads for processing accord tasks)
>> 
>> CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint, store_id int, 
>> PRIMARY KEY (epoch, store_id));
>> 
>> In this example the table changed the schema in a way that could break 
>> users, so this normally is not allowed.
>> 
>> Since we don’t really have a way to define something experimental other than 
>> NEWS.txt, we kinda get stuck with this table and are forced to make new 
>> versions and maintain them for a long time (in this example we would have 
>> epochs and epochs_v2)… it would be nice if we could define a way to express 
>> that tables are free to be changed (modified or even deleted) and the life 
>> cycle for them….
>> 
>> I propose that we allow such a case and make changes to the UX (as best as 
>> we can) to warn about this:
>> 
>> 1) update NEWS.txt to denote that the feature is experimental
>> 2) when you access an experimental table you get a ClientWarning stating 
>> that this is free to change
>> 3) the tables comments starts with “[EXPERIMENTAL]”
>> 
>> What do others think?
>> 
>> 

Re: [DISCUSS] Adding experimental vtables and rules around them

[Štefan Miklošovič]

I think that 2) (client warning on accessing vtable) is pretty obtrusive /
irritating, that means that every single time I would e.g. SELECT from such
a table, it would emit a warning to a client / cqlsh? I do not think that
is necessary.

What about putting such a table to system_experimental keyspace? Then it
would be about deciding when it is not considered experimental anymore and
once that happens, we just move it to the appropriate keyspace. I think
that it is better if users (rather admins) execute a query against
system_experimental.accord_epochs so they immediately know what they access
(something experimental) rather than being constantly reminded about that
by a client warning.

Maxim's idea about "experimental_virtual_tables_enabled" property is also
viable. However, I can't help it but that somehow reminds me a property for
a guardrail. Just a thought. I do not see yet how we could leverage it,
just saying how I perceive it.

On Wed, May 29, 2024 at 9:02 PM David Capwell  wrote:

> We agreed a long time ago that all new features are disabled by default,
> but I wanted to try to flesh out what we “should” do with something that
> might still be experimental and subject to breaking changes; I would prefer
> we keep this thread specific to vtables as the UX is different for
> different types of things…
>
> So, lets say we are adding a set of vtables but we are not 100% sure what
> the schema should be and we learn after the release that changes should be
> made, but that would end up breaking the table… we currently define
> everything as “don’t break this” so if we publish a table that isn’t 100%
> baked we are kinda stuck with it for a very very long time… I would like to
> define a way to expose vtables that are subject to change (breaking schema
> changes) across different release and rules around them (only in minor?
> Maybe even in patch?).
>
> Lets try to use a concrete example so everyone is on the same page.
>
> Accord is disabled by default (it is a new feature), so the vtables to
> expose internals would be expected to be undefined and not present on the
> instance.
>
> When accord is enabled (accord.enabled = true) we add a set of vtables:
>
> Epochs - shows what epochs are known to accord
> Cache - shows how the internal caches are performing
> Etc.
>
> Using epochs as an example it currently only shows a single column: the
> long epoch
>
> CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint PRIMARY KEY);
>
> Lets say we find that this table isn’t enough and we really need to scope
> it to each of the “stores” (threads for processing accord tasks)
>
> CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint, store_id int,
> PRIMARY KEY (epoch, store_id));
>
> In this example the table changed the schema in a way that could break
> users, so this normally is not allowed.
>
> Since we don’t really have a way to define something experimental other
> than NEWS.txt, we kinda get stuck with this table and are forced to make
> new versions and maintain them for a long time (in this example we would
> have epochs and epochs_v2)… it would be nice if we could define a way to
> express that tables are free to be changed (modified or even deleted) and
> the life cycle for them….
>
> I propose that we allow such a case and make changes to the UX (as best as
> we can) to warn about this:
>
> 1) update NEWS.txt to denote that the feature is experimental
> 2) when you access an experimental table you get a ClientWarning stating
> that this is free to change
> 3) the tables comments starts with “[EXPERIMENTAL]”
>
> What do others think?
>
>
>

Re: [DISCUSS] Adding experimental vtables and rules around them

[Maxim Muzafarov]

Hello everyone,

I like the idea of highlighting some of the experimental virtual
tables whose model might be changed in future releases.

As another option, we could add an @Experimetal annotation (or another
name) and a configuration parameter
experimental_virtula_tables_enabled (default is false). This, in turn,
means if a virtual table is experimental, it won't be registered in a
virtual keyspace unless the corresponding configuration parameter is
enabled. This also means that a user must implicitly enable an
experimental API, and prevent us from spamming the log with warnings.
All of this does not preclude us from specifying the experimental
state of some virtual tables in the documentation.

On Wed, 29 May 2024 at 21:18, Abe Ratnofsky  wrote:
>
> I agree that ClientWarning is the best way to indicate the risk of using an 
> experimental feature directly to the user. Presenting information in the 
> client application's logs directly means that the person who wrote the query 
> is most likely to see the warning, rather than an operator who sees cluster 
> logs.
>
> I don't think it's necessary to attach a ClientWarning to every single client 
> response; a ClientWarning analog to NoSpamLogger would be useful for this 
> ("warn a client at most once per day").
>
> This would also be useful for warning on usage of deprecated features.
>
> > On May 29, 2024, at 3:01 PM, David Capwell  wrote:
> >
> > We agreed a long time ago that all new features are disabled by default, 
> > but I wanted to try to flesh out what we “should” do with something that 
> > might still be experimental and subject to breaking changes; I would prefer 
> > we keep this thread specific to vtables as the UX is different for 
> > different types of things…
> >
> > So, lets say we are adding a set of vtables but we are not 100% sure what 
> > the schema should be and we learn after the release that changes should be 
> > made, but that would end up breaking the table… we currently define 
> > everything as “don’t break this” so if we publish a table that isn’t 100% 
> > baked we are kinda stuck with it for a very very long time… I would like to 
> > define a way to expose vtables that are subject to change (breaking schema 
> > changes) across different release and rules around them (only in minor?  
> > Maybe even in patch?).
> >
> > Lets try to use a concrete example so everyone is on the same page.
> >
> > Accord is disabled by default (it is a new feature), so the vtables to 
> > expose internals would be expected to be undefined and not present on the 
> > instance.
> >
> > When accord is enabled (accord.enabled = true) we add a set of vtables:
> >
> > Epochs - shows what epochs are known to accord
> > Cache - shows how the internal caches are performing
> > Etc.
> >
> > Using epochs as an example it currently only shows a single column: the 
> > long epoch
> >
> > CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint PRIMARY KEY);
> >
> > Lets say we find that this table isn’t enough and we really need to scope 
> > it to each of the “stores” (threads for processing accord tasks)
> >
> > CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint, store_id int, 
> > PRIMARY KEY (epoch, store_id));
> >
> > In this example the table changed the schema in a way that could break 
> > users, so this normally is not allowed.
> >
> > Since we don’t really have a way to define something experimental other 
> > than NEWS.txt, we kinda get stuck with this table and are forced to make 
> > new versions and maintain them for a long time (in this example we would 
> > have epochs and epochs_v2)… it would be nice if we could define a way to 
> > express that tables are free to be changed (modified or even deleted) and 
> > the life cycle for them….
> >
> > I propose that we allow such a case and make changes to the UX (as best as 
> > we can) to warn about this:
> >
> > 1) update NEWS.txt to denote that the feature is experimental
> > 2) when you access an experimental table you get a ClientWarning stating 
> > that this is free to change
> > 3) the tables comments starts with “[EXPERIMENTAL]”
> >
> > What do others think?
> >
> >
>

Re: [DISCUSS] Adding experimental vtables and rules around them

[Abe Ratnofsky]

I agree that ClientWarning is the best way to indicate the risk of using an 
experimental feature directly to the user. Presenting information in the client 
application's logs directly means that the person who wrote the query is most 
likely to see the warning, rather than an operator who sees cluster logs.

I don't think it's necessary to attach a ClientWarning to every single client 
response; a ClientWarning analog to NoSpamLogger would be useful for this 
("warn a client at most once per day").

This would also be useful for warning on usage of deprecated features.

> On May 29, 2024, at 3:01 PM, David Capwell  wrote:
> 
> We agreed a long time ago that all new features are disabled by default, but 
> I wanted to try to flesh out what we “should” do with something that might 
> still be experimental and subject to breaking changes; I would prefer we keep 
> this thread specific to vtables as the UX is different for different types of 
> things…
> 
> So, lets say we are adding a set of vtables but we are not 100% sure what the 
> schema should be and we learn after the release that changes should be made, 
> but that would end up breaking the table… we currently define everything as 
> “don’t break this” so if we publish a table that isn’t 100% baked we are 
> kinda stuck with it for a very very long time… I would like to define a way 
> to expose vtables that are subject to change (breaking schema changes) across 
> different release and rules around them (only in minor?  Maybe even in 
> patch?).
> 
> Lets try to use a concrete example so everyone is on the same page.
> 
> Accord is disabled by default (it is a new feature), so the vtables to expose 
> internals would be expected to be undefined and not present on the instance.
> 
> When accord is enabled (accord.enabled = true) we add a set of vtables:
> 
> Epochs - shows what epochs are known to accord
> Cache - shows how the internal caches are performing
> Etc.
> 
> Using epochs as an example it currently only shows a single column: the long 
> epoch
> 
> CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint PRIMARY KEY);
> 
> Lets say we find that this table isn’t enough and we really need to scope it 
> to each of the “stores” (threads for processing accord tasks)
> 
> CREATE VIRTUAL TABLE system_accord.epochs (epoch bigint, store_id int, 
> PRIMARY KEY (epoch, store_id));
> 
> In this example the table changed the schema in a way that could break users, 
> so this normally is not allowed.
> 
> Since we don’t really have a way to define something experimental other than 
> NEWS.txt, we kinda get stuck with this table and are forced to make new 
> versions and maintain them for a long time (in this example we would have 
> epochs and epochs_v2)… it would be nice if we could define a way to express 
> that tables are free to be changed (modified or even deleted) and the life 
> cycle for them….
> 
> I propose that we allow such a case and make changes to the UX (as best as we 
> can) to warn about this:
> 
> 1) update NEWS.txt to denote that the feature is experimental
> 2) when you access an experimental table you get a ClientWarning stating that 
> this is free to change
> 3) the tables comments starts with “[EXPERIMENTAL]”
> 
> What do others think?
> 
>