Функции 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
Следующие версии драйверов Cassandra поддерживаются Azure Cosmos DB для Apache 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 — нет.
*** Пользовательские метки времени и срок жизни, заданный с помощью параметра 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 |
No |
ALTER TABLE |
Да |
ALTER TYPE |
No |
ALTER USER |
No |
BATCH |
Да (только в незарегистрированном пакете) |
COMPACT STORAGE |
Н/д (служба PaaS) |
CREATE AGGREGATE |
No |
CREATE CUSTOM INDEX (SASI) |
No |
CREATE INDEX |
Да (включая именованные индексы , но полная коллекция FROZEN не поддерживается) |
CREATE FUNCTION |
No |
CREATE KEYSPACE (параметры репликации игнорируются) |
Да |
CREATE MATERIALIZED VIEW |
Да |
CREATE TABLE |
Да |
CREATE TRIGGER |
No |
CREATE TYPE |
Да |
CREATE ROLE |
Нет |
CREATE USER (не рекомендуется в собственном Apache Cassandra) |
No |
DELETE |
Да |
DISTINCT |
No |
DROP AGGREGATE |
No |
DROP FUNCTION |
No |
DROP INDEX |
Да |
DROP KEYSPACE |
Да |
DROP MATERIALIZED VIEW |
Да |
DROP ROLE |
No |
DROP TABLE |
Да |
DROP TRIGGER |
No |
DROP TYPE |
Да |
DROP USER (не рекомендуется в собственном Apache Cassandra) |
No |
GRANT |
No |
INSERT |
Да |
LIST PERMISSIONS |
No |
LIST ROLES |
No |
LIST USERS (не рекомендуется в собственном Apache Cassandra) |
No |
REVOKE |
No |
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 |
No |
DESCRIBE |
Да |
cqlshExpand |
No |
EXIT |
Да |
LOGIN |
Н/П (функция CQL не поддерживается USER, поэтому LOGIN не нужно использовать) |
PAGING |
Да |
SERIAL CONSISTENCY * |
Н/П |
SHOW |
Да |
SOURCE |
Да |
TRACING |
N/A (API для Cassandra поддерживает Azure Cosmos DB — используйте ведение журнала диагностики для устранения неполадок) |
Примечание.
В Azure Cosmos DB согласованность действует иначе, дополнительные сведения об этом см. здесь.
Поддержка JSON
| Команда | Поддерживается |
|---|---|
SELECT JSON |
Да |
INSERT JSON |
Да |
fromJson() |
No |
toJson() |
No |
Ограничения API для Cassandra
Azure Cosmos DB для Apache Cassandra не имеет ограничений на размер данных, хранящихся в таблице. В таблицах могут храниться сотни терабайт или петабайт данных с соблюдением ограничений для ключей секций. Каждый эквивалент сущности или строки не имеет никаких ограничений на число столбцов. Однако общий размер сущности не должен превышать 2 МБ. Объем данных на ключ секции не может превышать 20 ГБ, как и во всех других API.
Инструменты
Azure Cosmos DB для Apache Cassandra — это управляемая платформа служб. Этой платформе не требуются расходы на управление или такие служебные программы, как сборщик мусора, виртуальная машина Java (JVM) и Nodetool для управления кластером. Она поддерживает cqlsh и другие средства, использующее совместимость с двоичным CQLv4.
- Кроме того, для управления учетной записью применяются обозреватель данных на портале Azure, метрики, журналы диагностики, PowerShell и интерфейс командной строки.
Оболочка 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. Убедитесь, что вы используете только версии 3.11 открытый код версии Apache Cassandra CQLSH при подключении к API для Cassandra.
Windows:
- Установите Python 3
- Установка PIP
- Перед установкой PIP скачайте файл get-pip.py.
- Запустите командную строку, если она еще не открыта. Для этого откройте панель поиска Windows, введите cmd и выберите значок.
- Затем выполните следующую команду, чтобы скачать файл get-pip.py:
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py - Установите PIP в Windows
python get-pip.py
- Проверьте установку PIP (найдите сообщение из шага 3, чтобы проверить, в какую папку был установлен PIP, а затем перейдите в эту папку и выполните команду pip help).
- Установите CQLSH с помощью PIP
pip3 install cqlsh==5.0.3
- Установите Python 2
- Запустите 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 и центра обработки данных в команде "Создать пространство ключей" в настоящее время игнорируются. Для добавления регионов система использует базовый метод репликации глобального распространения Azure Cosmos DB. Если необходимо присутствие данных между регионами, вы можете включить их на уровне учетной записи с помощью PowerShell, интерфейса командной строки или портала. Дополнительные сведения см. в статье Добавление регионов. Невозможно отключить Durable_writes, потому что Azure Cosmos DB гарантирует длительность каждой записи. В каждом регионе Azure Cosmos DB реплицирует данные по набору реплик, который состоит из 4 реплик. Конфигурацию этого набора реплик невозможно изменить.
При создании таблицы игнорируются все параметры, кроме gc_grace_seconds, для которого должно быть задано значение ноль. Пространство ключей и таблица имеют дополнительную опцию с именем "cosmosdb_provisioned_throughput" с минимальным значением 400 единиц запроса/секунду. Пропускная способность пространства ключей позволяет разделять пропускную способность между несколькими таблицами, и это полезно для сценариев, когда не все таблицы используют предоставленную пропускную способность. Команда "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.
Следующие шаги
- Начало работы с созданием API для учетной записи Cassandra, базы данных и таблицы с помощью приложения Java