Поделиться через


Функции Apache Cassandra, поддерживаемые Azure Cosmos DB для Apache Cassandra

Область применения: Кассандра

Azure Cosmos DB — это многомодельная служба базы данных от Microsoft, распространяемая по всему миру. Вы можете взаимодействовать с Azure Cosmos DB для Apache Cassandra с помощью драйверов клиентов Cassandra Query Language (CQL) Binary Protocol версии 4, совместимых с клиентскими драйверами Cassandra с открытым исходным кодом.

Используя Azure Cosmos DB для Apache Cassandra, вы можете воспользоваться преимуществами API Apache Cassandra и корпоративными возможностями, предоставляемыми Azure Cosmos DB. Корпоративные возможности включают глобальное распределение, масштабирование с автоматическим секционированием, гарантии доступности и низкой задержки, шифрование данных в состоянии покоя и резервное копирование.

Протокол Cassandra

Azure Cosmos DB для Apache Cassandra совместим с API языка запросов Cassandra версии 3.11. Он обратно совместим с версией 2.x. Поддерживаемые команды CQL, средства, ограничения и исключения перечислены далее в этой статье. Любой драйвер клиента, который понимает эти протоколы, должен иметь возможность подключаться к Azure Cosmos DB для Apache Cassandra.

Управляемый экземпляр Azure для Apache Cassandra

Для некоторых клиентов адаптация к API для Cassandra может быть проблемой из-за различий в поведении и конфигурации, особенно для миграции лифтов и смен. Если компонент, критически важный для вашего приложения, указан как не поддерживаемый далее в этой статье, рассмотрите возможность использования Управляемого экземпляра Azure для Apache Cassandra. Эта служба является собственным сервисом Azure для размещения и обслуживания чистых кластеров Apache Cassandra с открытым исходным кодом, обеспечивая 100% совместимость с%.

Драйвер Cassandra

Azure Cosmos DB для Apache Cassandra поддерживает следующие версии драйверов Cassandra:

Типы данных CQL

Azure Cosmos DB для Apache Cassandra поддерживает следующие типы данных CQL:

Тип Поддерживается
ascii Да
bigint Да
blob Да
boolean Да
counter Да
date Да
decimal Да
double Да
float Да
frozen Да
inet Да
int Да
list Да
set Да
smallint Да
text Да
time Да
timestamp Да
timeuuid Да
tinyint Да
tuple Да
uuid Да
varchar Да
varint Да
tuples Да
udts Да
map Да

Static поддерживается для объявления типа данных.

Функции CQL

Azure Cosmos DB для Apache Cassandra поддерживает следующие функции CQL:

Команда Поддерживается
Token * Да
ttl *** Да
writetime *** Да
cast ** Да

Примечание.

* API для Cassandra поддерживает маркер в виде проекции или селектора и разрешает только токен(pk) в левой части предложения where. Например, WHERE token(pk) > 1024 поддерживается, но WHERE token(pk) > token(100) — нет. ** Функция cast() не вложена в API для Cassandra. Например, SELECT cast(count as double) FROM myTable поддерживается, но SELECT avg(cast(count as double)) FROM myTable — нет. Пользовательские метки времени и TTL, указанные параметром USING , применяются на уровне строки (а не для каждой ячейки).

Агрегатные функции:

Команда Поддерживается
avg Да
count Да
min Да
max Да
sum Да

Примечание.

Агрегатная функция работает с обычными столбцами, но агрегирование для кластеризованных столбцов не поддерживается.

Функции преобразования больших двоичных объектов

Команда Поддерживается
typeAsBlob(value) Да
blobAsType(value) Да

Функции UUID и timeuuid

Команда Поддерживается
dateOf() Да
now() Да
minTimeuuid() Да
unixTimestampOf() Да
toDate(timeuuid) Да
toTimestamp(timeuuid) Да
toUnixTimestamp(timeuuid) Да
toDate(timestamp) Да
toUnixTimestamp(timestamp) Да
toTimestamp(date) Да
toUnixTimestamp(date) Да

Команды CQL

Azure Cosmos DB поддерживает следующие команды базы данных в API для учетных записей Cassandra.

Команда Поддерживается
ALLOW FILTERING Да
ALTER KEYSPACE Н/д (служба PaaS, внутреннее управление репликацией)
ALTER MATERIALIZED VIEW Да
ALTER ROLE нет
ALTER TABLE Да
ALTER TYPE нет
ALTER USER нет
BATCH Да (только в незарегистрированном пакете)
COMPACT STORAGE Н/д (служба PaaS)
CREATE AGGREGATE нет
CREATE CUSTOM INDEX (SASI) нет
CREATE INDEX Да (включая именованные индексы, но полная коллекция FROZEN не поддерживается)
CREATE FUNCTION нет
CREATE KEYSPACE (параметры репликации игнорируются) Да
CREATE MATERIALIZED VIEW Да
CREATE TABLE Да
CREATE TRIGGER нет
CREATE TYPE Да
CREATE ROLE нет
CREATE USER (не рекомендуется в собственном Apache Cassandra) нет
DELETE Да
DISTINCT нет
DROP AGGREGATE нет
DROP FUNCTION нет
DROP INDEX Да
DROP KEYSPACE Да
DROP MATERIALIZED VIEW Да
DROP ROLE нет
DROP TABLE Да
DROP TRIGGER нет
DROP TYPE Да
DROP USER (не рекомендуется в собственном Apache Cassandra) нет
GRANT нет
INSERT Да
LIST PERMISSIONS нет
LIST ROLES нет
LIST USERS (не рекомендуется в собственном Apache Cassandra) нет
REVOKE нет
SELECT Да
UPDATE Да
TRUNCATE Да
USE Да

Упрощенные транзакции (LWT)

Компонент Поддерживается
DELETE IF EXISTS Да
DELETE conditions Да
INSERT IF NOT EXISTS Да
UPDATE IF EXISTS Да
UPDATE IF NOT EXISTS Да
UPDATE conditions Да

Примечание.

В настоящий момент легковесные транзакции не поддерживаются для учетных записей, в которых включена запись в нескольких регионах.

Команды оболочки CQL

Azure Cosmos DB поддерживает следующие команды базы данных в API для учетных записей Cassandra.

Команда Поддерживается
CAPTURE Да
CLEAR Да
CONSISTENCY * Н/П
COPY нет
DESCRIBE Да
cqlshExpand нет
EXIT Да
LOGIN N/A (функция USER CQL не поддерживается, поэтому LOGIN является избыточной)
PAGING Да
SERIAL CONSISTENCY * Н/П
SHOW Да
SOURCE Да
TRACING N/A (API для Cassandra поддерживает Azure Cosmos DB — используйте ведение журнала диагностики для устранения неполадок)

Примечание.

Согласованность работает по-разному в Azure Cosmos DB. Дополнительные сведения см. в разделе Apache Cassandra и Azure Cosmos DB о уровнях согласованности Apache Cassandra.

Поддержка JSON

Команда Поддерживается
SELECT JSON Да
INSERT JSON Да
fromJson() нет
toJson() нет

Ограничения API для Cassandra

Azure Cosmos DB для Apache Cassandra не ограничивает размер данных, хранящихся в таблице. В таблицах могут храниться сотни терабайт или петабайт данных с соблюдением ограничений для ключей секций. Аналогичным образом каждый эквивалент сущности или строки не имеет никаких ограничений на количество столбцов. Общий размер сущности не должен превышать 2 МБ. Данные на ключ раздела не могут превышать 20 ГБ, как и во всех остальных API.

Инструменты

Azure Cosmos DB для Apache Cassandra — это управляемая платформа служб. Платформа не требует дополнительных затрат на управление или служебных программ, таких как сборщик мусора, виртуальная машина Java (JVM) и средство узла для управления кластером. Поддерживаются такие средства, как cqlsh, которые используют совместимость с Binary CQLv4.

  • Обозреватель данных портала Azure, метрики, диагностика журналов, PowerShell и CLI — это другие поддерживаемые механизмы управления учетной записью.

Оболочка CQL

Вы можете подключиться к API для Cassandra в Azure Cosmos DB с помощью CQLSH, установленного на локальном компьютере. Она входит в состав Apache Cassandra 3.11 и работает без дополнительной настройки, задавая переменные среды. В следующих разделах приведены инструкции по установке, настройке и подключению к API для Cassandra в Azure Cosmos DB в Windows или Linux с помощью CQLSH.

Предупреждение

Подключения к Azure Cosmos DB для Apache Cassandra не работают с версиями DataStax Enterprise (DSE) или Cassandra 4.0 CQLSH. Убедитесь, что при подключении к API для Cassandra используется только версия CQLSH Apache Cassandra с открытым исходным кодом версии 3.11.

Виндоус:

  1. Установите Python 3.

  2. Установите PIP.

    1. Перед установкой PIP скачайте файл get-pip.py .
    2. Запустите окно командной строки, если оно еще не открыто. Для этого откройте панель поиска Windows, введите cmd и выберите значок.
    3. Затем выполните следующую команду, чтобы скачать файл get-pip.py :
    curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py 
    
  3. Установите PIP в Windows:

    python get-pip.py
    
  4. Проверьте установку PIP. Найдите сообщение из шага 3, чтобы подтвердить, в какой папке была установлена папка PIP. Затем перейдите в эту папку и выполните команду pip help.

  5. Установите CQLSH с помощью PIP:

    pip3 install cqlsh==5.0.3
    
  6. Установите Python 2.

  7. Запустите CQLSH, используя механизм проверки подлинности.

Примечание.

Необходимо задать переменные среды, чтобы указать папку Python 2.

Установите в Unix/Linux/Mac:

# Install default-jre and default-jdk
sudo apt install default-jre
sudo apt-get update
sudo apt install default-jdk

# Import the Baltimore CyberTrust root certificate:
curl https://cacert.omniroot.com/bc2025.crt > bc2025.crt
keytool -importcert -alias bc2025ca -file bc2025.crt

# Install the Cassandra libraries in order to get CQLSH:
echo "deb https://downloads.apache.org/cassandra/debian 311x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
curl https://downloads.apache.org/cassandra/KEYS | sudo apt-key add -
sudo apt-get update
sudo apt-get install cassandra=3.11.13

Подключение с помощью Unix/Linux/Mac:

# Export the SSL variables:
export SSL_VERSION=TLSv1_2
export SSL_VALIDATE=false

# Connect to Azure Cosmos DB for Apache Cassandra:
cqlsh <YOUR_ACCOUNT_NAME>.cassandra.cosmosdb.azure.com 10350 -u <YOUR_ACCOUNT_NAME> -p <YOUR_ACCOUNT_PASSWORD> --ssl --protocol-version=4

Подключение к Docker:

docker run -it --rm -e SSL_VALIDATE=false -e SSL_VERSION=TLSv1_2 cassandra:3.11 cqlsh <account_name>.cassandra.cosmos.azure.com 10350 -u <YOUR_ACCOUNT_NAME> -p <YOUR_ACCOUNT_PASSWORD> --ssl

Все операции CRUD, выполняемые через совместимый пакет SDK для CQL версии 4, возвращают дополнительные сведения об ошибках и единицах запросов, используемых. Чтобы обеспечить наиболее эффективное использование подготовленной пропускной способности, команды DELETE и UPDATE должны обрабатываться с учетом управления ресурсами.

Примечание.

Значение gc_grace_seconds должно быть равно нулю, если указано.

var tableInsertStatement = table.Insert(sampleEntity); 
var insertResult = await tableInsertStatement.ExecuteAsync(); 
 
foreach (string key in insertResult.Info.IncomingPayload) 
        { 
            byte[] valueInBytes = customPayload[key]; 
            double value = Encoding.UTF8.GetString(valueInBytes); 
            Console.WriteLine($"CustomPayload:  {key}: {value}"); 
        } 

Сопоставление согласованности

Azure Cosmos DB для Apache Cassandra предоставляет выбор согласованности для операций чтения. Дополнительные сведения см. в разделе "Сопоставление уровней согласованности".

Управление разрешениями и ролями

Azure Cosmos DB поддерживает управление доступом на основе ролей Azure (Azure RBAC) для подготовки, смены ключей, просмотра метрик, а также пароли (ключи) для чтения и записи или только для чтения, которые можно получить с помощью портала Azure. Azure Cosmos DB не поддерживает роли для действий CRUD.

Параметры пространства ключей и таблицы

В настоящее время параметры имени региона, класса, replication_factor и центра обработки данных в команде CREATE KEYSPACE игнорируются. Для добавления регионов система использует базовый метод репликации глобального распространения Azure Cosmos DB. Если требуется наличие данных между регионами, его можно включить на уровне учетной записи с помощью PowerShell, CLI или портала Azure. Дополнительные сведения см. в разделе "Добавление регионов" в учетную запись базы данных.

Невозможно отключить Durable_writes, потому что Azure Cosmos DB гарантирует длительность каждой записи. В каждом регионе Azure Cosmos DB реплицирует данные по набору реплик, который состоит из 4 реплик. Конфигурацию этого набора реплик невозможно изменить.

Все параметры игнорируются при создании таблицы, за исключением gc_grace_secondsтого, что должно быть равно нулю. Пространство ключей и таблица имеют дополнительный параметр cosmosdb_provisioned_throughput с минимальным значением 400 RU/с. Пропускная способность пространства ключей позволяет распределять пропускную способность между несколькими таблицами. Это полезно для сценариев, когда все таблицы не используют подготовленную пропускную способность. Эта ALTER TABLE команда позволяет изменять подготовленную пропускную способность в разных регионах.

CREATE KEYSPACE sampleks WITH REPLICATION = {  'class' : 'SimpleStrategy'} AND cosmosdb_provisioned_throughput=2000;  

CREATE TABLE sampleks.t1(user_id int PRIMARY KEY, lastname text) WITH cosmosdb_provisioned_throughput=2000; 

ALTER TABLE gks1.t1 WITH cosmosdb_provisioned_throughput=10000 ;

Вторичный индекс

API для Cassandra поддерживает вторичные индексы для всех типов данных, кроме замороженных типов коллекций, десятичных и вариантных типов.

Использование политики повторных подключений Cassandra

Azure Cosmos DB — это система управления ресурсами. Некоторые операции можно выполнять в заданной секунде на основе единиц запросов, потребляемых операциями. Если приложение превышает это ограничение в определенной секунде, запросы ограничиваются скоростью и возникают исключения. API для Cassandra в Azure Cosmos DB преобразует эти исключения в перегруженные ошибки в собственном протоколе Cassandra.

Чтобы убедиться, что ваше приложение может перехватывать и повторять запросы при лимитировании запросов, предоставляются расширения spark и Java. См. также примеры кода Java для драйверов Datastax версии 3 и версии 4 при подключении к API для Cassandra в Azure Cosmos DB. Если вы используете другие пакеты SDK для доступа к API Cassandra в Azure Cosmos DB, создайте политику повторных попыток, чтобы повторить эти исключения. Кроме того, включите повторные попытки на стороне сервера для API для Cassandra.

Следующие шаги