The remove_versions operator removes selected versions of an array.

Synopsis

remove_versions(namedArray, oldestVersionToKeep); remove_versions(namedArray, firstVersionToRemove, oldestVersionToKeep); remove_versions(namedArray, keep: count); remove_versions(namedArray);

Summary

In the Synopsis section, the first form of the remove_versions operator removes all versions of namedArray that are older than oldestVersionToKeep.
The second form removes versions starting at firstVersionToRemove up to but not including oldestVersionToKeep. To remove the most recent version(s), specify oldestVersionToKeep using the special token max_version.
The third form keeps the count most recent versions, removing all earlier versions.
The fourth form removes all but the latest version; it is the same as using keep:1.

Removing versions that do not exist is not an error.

Inputs

namedArray - The name of the array from which you are removing versions.
firstVersionToRemove - Remove versions beginning with this one, up to but not including oldestVersionToSave. If not explicitly specified, firstVersionToRemove is version 1.
oldestVersionToKeep - This and all later versions will be kept. If oldestVersionToKeep is max_version, then all versions from firstVersionToRemove onward are removed.
keep:N - keep latest N versions

Examples

From the command shell, use iquery to create an array and store several versions of data into it:

$ iquery -aq "create array A<val:double>[i=0:4]"
Query was executed successfully
$ for x in $(seq 10) ;do iquery -naq "store(build(A, 10 + $x), A)" ;done 
Query was executed successfully 
Query was executed successfully 
Query was executed successfully 
Query was executed successfully 
Query was executed successfully 
Query was executed successfully 
Query was executed successfully
Query was executed successfully
Query was executed successfully
Query was executed successfully
$

Use list('arrays', true) and versions(A) to see all versions of the array, and inspect the values from some older versions:

$ iquery -a
AFL% project(list('arrays', true), name, uaid, aid);
{No} name,uaid,aid
{0} 'A',182,182
{1} 'A@1',182,183
{2} 'A@10',182,192
{3} 'A@2',182,184
{4} 'A@3',182,185
{5} 'A@4',182,186
{6} 'A@5',182,187
{7} 'A@6',182,188
{8} 'A@7',182,189
{9} 'A@8',182,190
{10} 'A@9',182,191
AFL% 
AFL% versions(A);
{No} version_id,timestamp
{1} 1,'2023-04-04 21:35:22'
{2} 2,'2023-04-04 21:35:22'
{3} 3,'2023-04-04 21:35:22'
{4} 4,'2023-04-04 21:35:23'
{5} 5,'2023-04-04 21:35:23'
{6} 6,'2023-04-04 21:35:23'
{7} 7,'2023-04-04 21:35:23'
{8} 8,'2023-04-04 21:35:23'
{9} 9,'2023-04-04 21:35:23'
{10} 10,'2023-04-04 21:35:23'
AFL% 
AFL% scan(A@5);
{i} val
{0} 15
{1} 15
{2} 15
{3} 15
{4} 15
AFL% 
AFL% scan(A@7);
{i} val
{0} 17
{1} 17
{2} 17
{3} 17
{4} 17
AFL%

Remove versions 4, 5, and 6:

AFL% remove_versions(A, 4, 7);
AFL% remove_versions(A, 4, 7);
Query was executed successfully
AFL% 
AFL% versions(A);
{No} version_id,timestamp
{1} 1,'2023-04-04 21:35:22'
{2} 2,'2023-04-04 21:35:22'
{3} 3,'2023-04-04 21:35:22'
{4} 7,'2023-04-04 21:35:23'
{5} 8,'2023-04-04 21:35:23'
{6} 9,'2023-04-04 21:35:23'
{7} 10,'2023-04-04 21:35:23'
AFL% 
AFL% scan(A@6);
UserQueryException in file: src/query/parser/Translator.cpp function: createArrayReferenceParam line: 1605 instance: s0-i0 (0)
Error id: scidb::SCIDB_SE_QPROC::SCIDB_LE_ARRAY_VERSION_DOESNT_EXIST
Error description: Query processor error. Specified version of array 'public.A' does not exist.
Failed query id: 0.1680644432657560699
scan(A@6)
       ^
AFL% scan(A@7);
{i} val
{0} 17
{1} 17
{2} 17
{3} 17
{4} 17
AFL%

Remove all recent versions starting with version 9:

AFL% remove_versions(A, 9, max_version);
Query was executed successfully
AFL% versions(A);
{No} version_id,timestamp
{1} 1,'2023-04-04 21:35:22'
{2} 2,'2023-04-04 21:35:22'
{3} 3,'2023-04-04 21:35:22'
{4} 7,'2023-04-04 21:35:23'
{5} 8,'2023-04-04 21:35:23'
AFL% scan(A);
{i} val
{0} 18
{1} 18
{2} 18
{3} 18
{4} 18
AFL%

Remove versions 1 and 2:

AFL% remove_versions(A, 3);
Query was executed successfully
AFL% versions(A);
{No} version_id,timestamp
{1} 3,'2023-04-04 21:35:22'
{2} 7,'2023-04-04 21:35:23'
{3} 8,'2023-04-04 21:35:23'
AFL%

Keep only the two most recent versions:

AFL% remove_versions(A, keep:2);
Query was executed successfully
AFL% versions(A);
{No} version_id,timestamp
{1} 7,'2023-04-04 21:35:23'
{2} 8,'2023-04-04 21:35:23'
AFL%

Keep only the most recent version:

AFL% remove_versions(A);
Query was executed successfully
AFL% versions(A);
{No} version_id,timestamp
{1} 8,'2023-04-04 21:35:23'
AFL%