Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu

Caution

You're viewing documentation for an unstable version of Scylla Dev. Switch to the latest stable version.

Scylla Dev Design Notes Scylla CQL extensions

Scylla CQL extensions¶

Scylla extends the CQL language to provide a few extra features. This document lists those extensions.

BYPASS CACHE clause¶

The BYPASS CACHE clause on SELECT statements informs the database that the data being read is unlikely to be read again in the near future, and also was unlikely to have been read in the near past; therefore no attempt should be made to read it from the cache or to populate the cache with the data. This is mostly useful for range scans; these typically process large amounts of data with no temporal locality and do not benefit from the cache.

The clause is placed immediately after the optional ALLOW FILTERING clause:

SELECT ... FROM ...
WHERE ...
ALLOW FILTERING          -- optional
BYPASS CACHE

“Paxos grace seconds” per-table option¶

The paxos_grace_seconds option is used to set the amount of seconds which are used to TTL data in paxos tables when using LWT queries against the base table.

This value is intentionally decoupled from gc_grace_seconds since, in general, the base table could use completely different strategy to garbage collect entries, e.g. can set gc_grace_seconds to 0 if it doesn’t use deletions and hence doesn’t need to repair.

However, paxos tables still rely on repair to achieve consistency, and the user is required to execute repair within paxos_grace_seconds.

Default value is equal to DEFAULT_GC_GRACE_SECONDS, which is 10 days.

The option can be specified at CREATE TABLE or ALTER TABLE queries in the same way as other options by using WITH clause:

CREATE TABLE tbl ...
WITH paxos_grace_seconds=1234

USING TIMEOUT¶

TIMEOUT extension allows specifying per-query timeouts. This parameter accepts a single duration and applies it as a timeout specific to a single particular query. The parameter is supported for prepared statements as well. The parameter acts as part of the USING clause, and thus can be combined with other parameters - like timestamps and time-to-live. In order for this parameter to be effective for read operations as well, it’s possible to attach USING clause to SELECT statements.

Examples:

	SELECT * FROM t USING TIMEOUT 200ms;
	INSERT INTO t(a,b,c) VALUES (1,2,3) USING TIMESTAMP 42 AND TIMEOUT 50ms;

Working with prepared statements works as usual - the timeout parameter can be explicitly defined or provided as a marker:

	SELECT * FROM t USING TIMEOUT ?;
	INSERT INTO t(a,b,c) VALUES (?,?,?) USING TIMESTAMP 42 AND TIMEOUT 50ms;

Keyspace storage options¶

Storage options allows specifying the storage format assigned to a keyspace. The default storage format is LOCAL, which simply means storing all the sstables in a local directory. Experimental support for S3 storage format is also added. This option is not fully implemented yet, but it will allow storing sstables in a shared, S3-compatible object store.

Storage options can be specified via CREATE KEYSPACE or ALTER KEYSPACE statement and it’s formatted as a map of options - similarly to how replication strategy is handled.

Examples:

CREATE KEYSPACE ks
    WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 3 }
    AND STORAGE = { 'type' : 'S3', 'bucket' : '/tmp/b1', 'endpoint' : 'localhost' } ;
ALTER KEYSPACE ks WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 3 }
    AND STORAGE = { 'type' : 'S3', 'bucket': '/tmp/b2', 'endpoint' : 'localhost' } ;

Storage options can be inspected by checking the new system schema table: system_schema.scylla_keyspaces:

    cassandra@cqlsh> select * from system_schema.scylla_keyspaces;
    
     keyspace_name | storage_options                                | storage_type
    ---------------+------------------------------------------------+--------------
               ksx | {'bucket': '/tmp/xx', 'endpoint': 'localhost'} |           S3

PRUNE MATERIALIZED VIEW statements¶

A special statement is dedicated for pruning ghost rows from materialized views. Ghost row is an inconsistency issue which manifests itself by having rows in a materialized view which do not correspond to any base table rows. Such inconsistencies should be prevented altogether and Scylla is striving to avoid them, but if they happen, this statement can be used to restore a materialized view to a fully consistent state without rebuilding it from scratch.

Example usages:

  PRUNE MATERIALIZED VIEW my_view;
  PRUNE MATERIALIZED VIEW my_view WHERE token(v) > 7 AND token(v) < 1535250;
  PRUNE MATERIALIZED VIEW my_view WHERE v = 19;

The statement works by fetching requested rows from a materialized view and then trying to fetch their corresponding rows from the base table. If it turns out that the base row does not exist, the row is considered a ghost row and is thus deleted. The statement implicitly works with consistency level ALL when fetching from the base table to avoid false positives. As the example shows, a materialized view can be pruned in one go, but one can also specify specific primary keys or token ranges, which is recommended in order to make the operation less heavyweight and allow for running multiple parallel pruning statements for non-overlapping token ranges.

Expressions¶

Lists elements for filtering¶

Subscripting a list in a WHERE clause is supported as are maps.

WHERE some_list[:index] = :value

Per-partition rate limit¶

The per_partition_rate_limit option can be used to limit the allowed rate of requests to each partition in a given table. When the cluster detects that the rate of requests exceeds configured limit, the cluster will start rejecting some of them in order to bring the throughput back to the configured limit. Rejected requests are less costly which can help reduce overload.

NOTE: Due to Scylla’s distributed nature, tracking per-partition request rates is not perfect and the actual rate of accepted requests may be higher up to a factor of keyspace’s RF. This feature should not be used to enforce precise limits but rather serve as an overload protection feature.

_NOTE): This feature works best when shard-aware drivers are used (rejected requests have the least cost).

Limits are configured separately for reads and writes. Some examples:

    ALTER TABLE t WITH per_partition_rate_limit = {
        'max_reads_per_second': 100,
        'max_writes_per_second': 200
    };

Limit reads only, no limit for writes:

    ALTER TABLE t WITH per_partition_rate_limit = {
        'max_reads_per_second': 200
    };

Rejected requests receive the scylla-specific “Rate limit exceeded” error. If the driver doesn’t support it, Config_error will be sent instead.

For more details, see:

  • Detailed design notes

  • Description of the rate limit exceeded error

PREVIOUS
The Compaction Controller
NEXT
Scylla CQL extensions
  • master
    • 4.6
    • 4.5
  • Scylla Developer Documentation
  • Alternator: DynamoDB API in Scylla
    • Getting Started With ScyllaDB Alternator
    • Scylla Alternator for DynamoDB users
  • Design Notes
    • IDL compiler
    • CDC
    • The Compaction Controller
    • Scylla CQL extensions
    • Scylla CQL extensions
    • CQL3 Type Mapping
    • Hinted Handoff Design
    • Performance Isolation in Scylla
    • CQL to Lua type mapping
    • Scylla Metrics
    • Migrating from users to roles
    • Paged queries
    • Parallel aggregations
    • Per-partition rate limiting
    • Protocol extensions to the Cassandra Native Protocol
    • Ports and protocols in Scylla
    • Intro
    • Raft application in Scylla
    • The group 0
    • Using Group 0 to perform schema changes
    • Redis API in Scylla
    • Repair based node operations
    • Reverse reads
    • Row Cache
    • Row level repair
    • Rust and C++
    • Secondary indexes in Scylla
    • Service Level Distributed Data
    • File format of the Scylla.db sstable component
    • sstables directory structure
    • System keyspace layout
    • Virtual tables in the system keyspace
    • System schema keyspace layout
    • WASM support for user-defined functions
  • Guides
    • Scylla RESTful API V2
    • Building Scylla
    • Debugging with GDB
    • Docker Hub Image
    • Logging in Scylla
    • Testing
    • Tracing
    • Virtual Tables
  • Contribute
    • Contributing to Scylla
    • Backport
    • Maintainer’s handbook
    • Review Checklist
  • Create an issue
  • Edit this page

On this page

  • Scylla CQL extensions
    • BYPASS CACHE clause
    • “Paxos grace seconds” per-table option
    • USING TIMEOUT
    • Keyspace storage options
    • PRUNE MATERIALIZED VIEW statements
    • Expressions
      • Lists elements for filtering
    • Per-partition rate limit
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© 2022, ScyllaDB. All rights reserved.
Last updated on 28 June 2022.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2