My view is that virtual tables should not automatically be treated as API-stable. They are for debugging / operator interaction, and intend to expose internal implementation-specific state that is liable to change across minors. We therefore must either avoid exposing internal state and significantly hamper their utility, or else we must reject API compatibility.
To avoid an earlier argument about this, Accord virtual tables are simply off by default, so that the user must read the commentary that they are not API stable when enabling them. It may be suboptimal for users to realise this mid-incident though, but I cannot promise API compatibility for deep internal state that may cease to exist entirely. My preference would be to standardise on a project policy of defaulting virtual tables to API unstable unless explicitly declared as stable (for programmatic access), and - if it makes some people happy - to report a client warning on first access to such a table. On 2026/09/08 12:51:01 Maxim Muzafarov wrote: > Hi Stefan, > > Thank you for bringing this topic up. I think there is still some room > for improvement here. > > Out of the options you outlined, I don't think the first option > excludes the second one. My preference would be to improve the API in > the 6.0 release, while still keeping it experimental for at least one > major release. This would give us some time to collect feedback from > real-world usage before treating the API as stable. > > We already had a discussion about experimental virtual tables and the > rules around them: > > [DISCUSS] Adding experimental vtables and rules around them > https://lists.apache.org/thread/xlv5rodt9v77rzrqssp3p63yjg0b88v4 > > A few additional thoughts from my side: > > 1. > If we want to change the UX or the schema of the metrics virtual > tables, I think it is better to do the larger changes in 6.0. This > way, users could expect only smaller or mostly cosmetic changes in > later releases rather than a complete redesign. > > At the same time, I think the expected usage patterns need to be > defined more clearly. Saying that there are "usability issues" does > not give us much direction unless we describe how users are expected > to query, filter, and export metrics. Otherwise, some of the proposed > changes may become a matter of preference rather than solving a > concrete problem. > > 2. > There is also a pending improvement waiting for a reviewer, which did > not receive the attention it deserved: > https://issues.apache.org/jira/browse/CASSANDRA-19666 > > This change improves the efficiency of bulk metrics exports > (benchmarks are attached to the issue). The issue also describes in > more detail the problems with keeping all metrics in a single large > collection, especially when querying or exporting them in bulk. > > I would therefore prefer to address the larger known UX and schema > issues in 6.0, while still keeping the API in an experimental state > for some time afterwards. This would give us more flexibility to make > smaller adjustments based on actual usage, rather than committing too > early to the current schema. > > On Mon, 7 Sept 2026 at 12:24, Štefan Miklošovič <[email protected]> > wrote: > > > > There is quite a thread on dev Slack discussing the implementation of > > virtual tables for metrics. Recently, there was also a lot of > > discussion on (2) where we initially removed a column in a virtual > > table which received a lot of pushback saying that it is a public API > > and we can not remove a column like that. > > > > Okay, fair enough. > > > > But when thinking about what was written in Slack about metrics and > > how vtables are modeled, I think that it is currently pending to be > > re-modelled quite a lot. We will very likely need to do this if we > > want to support e.g. more UX-friendly querying and scrapping of these > > metrics. Various people (Caleb, David) seem to be not satisfied with > > how system_metrics look like. (Please correct me if I am wrong). > > > > However, when 6.0 is out and we do not do anything about this, then by > > what was said in 21539 means that we will not be able to restructure > > vtable metrics and we will need to have yet another set of metric > > vtables on top of what we ship? > > > > What happens with virtual metrics tables after 6.0 when we will need > > to (massively) re-work their schemas? > > > > Possible options: > > > > 1) focus on its restructuralization before 6.0 is out because after > > that it will be effectively set in stone as that is our public API > > 2) mark it as experimental and object of further re-modelling > > 3) keep it as it is and never change it > > 4) ??? > > > > Regards > > > > (1) https://the-asf.slack.com/archives/CK23JSY2K/p1716324924466269 > > (2) https://issues.apache.org/jira/browse/CASSANDRA-21539 >
