Операции с битовыми картами

В Managed Valkey все управление битовыми картами выполняется командами Valkey. С полным списком команд Valkey вы можете ознакомиться в официальной документации Valkey.

Обратите внимание, что в Managed Valkey некоторые команды Valkey недоступны.

Чтобы прочитать значение бита, используйте команду GETBIT.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имя ключа с помощью итеративного обхода.

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение string.

5. Выполните команду:

   1
   GETBIT <имя ключа> <смещение>

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

   Команда вернет 0 или 1. Если ключ не существует или смещение выходит за пределы строки, вернется 0. Значение ключа сохранится. При другом типе значения команда вернет ошибку.

Чтобы получить количество битов со значением 1, используйте команду BITCOUNT.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имя ключа с помощью итеративного обхода.

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение string.

5. Выполните команду:

   1
   BITCOUNT <имя ключа> [<начало> <конец> [BYTE | BIT]]

   В команде:

   • <начало> и <конец> — границы диапазона, включая обе границы. Без диапазона будет обработана вся строка.
   • BYTE — указать границы в байтах. Этот вариант будет использован по умолчанию.
   • BIT — указать границы в битах.

   Индексация начинается с 0. Отрицательные границы отсчитываются от конца строки в выбранных единицах. -1 означает последний байт или бит.

   Команда вернет количество установленных битов. Если ключ не существует или диапазон пуст, вернется 0. Значение ключа сохранится.

Чтобы найти первый бит со значением 0 или 1, используйте команду BITPOS.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имя ключа с помощью итеративного обхода.

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение string.

5. Выполните команду:

   1
   BITPOS <имя ключа> <значение бита> [<начало> [<конец> [BYTE | BIT]]]

   В команде:

   • <значение бита> — 0 или 1.
   • <начало> и <конец> — границы поиска, включая обе границы. По умолчанию границы задаются в байтах. BIT переключит их на биты.
   • Отрицательные границы — позиции от конца строки в выбранных единицах.

   Команда вернет номер найденного бита от начала всей строки, независимо от границ поиска. Если бит 1 не найден, вернется -1.

   При поиске 0 без конечной границы строка будет считаться дополненной нулевыми битами справа. Если все имеющиеся биты равны 1, вернется позиция первого бита после строки. При явно заданном конце поиск ограничится диапазоном: если нулевого бита в нем нет, вернется -1.

   Для несуществующего ключа при поиске без диапазона вернется 0 для бита 0 или -1 для бита 1.

Чтобы прочитать целые числа из битовых полей без изменения строки, используйте команду BITFIELD_RO.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имя ключа с помощью итеративного обхода.

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение string.

5. Выполните команду:

   1
   BITFIELD_RO <имя ключа> GET <тип поля> <смещение> [GET <тип поля> <смещение> ...]

   В команде:

   • <тип поля> — i и число битов для знакового числа, например i16, или u и число битов для беззнакового, например u8. Допустимы i1–i64 и u1–u63.
   • <смещение> — неотрицательная позиция первого бита поля. Запись #N означает смещение на N полей указанной ширины. Например, для u8 смещение #2 равно 16 битам.

   Выбирайте ширину и позиции полей в соответствии со схемой хранения данных приложения.

   Команда вернет список чисел в порядке операций GET. Недостающие биты будут прочитаны как нулевые. Если ключ не существует, для каждого поля вернется 0, а ключ не будет создан.

Чтобы установить или сбросить отдельный бит, используйте команду SETBIT.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

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

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение string.

5. Выполните команду:

   1
   SETBIT <имя ключа> <смещение> <значение бита>

   В команде:

   • <смещение> — номер бита от 0 до 4294967295.
   • <значение бита> — 0 или 1. Например, значение 0 снимет флаг в выбранной позиции.

   Команда изменит бит и вернет его предыдущее значение. Если ключ не существует, команда создаст строку. При смещении за пределами строки она будет расширена, а промежуточные биты будут заполнены нулями. Сброс всех битов в 0 не удалит ключ.

Чтобы выполнить побитовую операцию и сохранить результат в отдельный ключ, используйте команду BITOP.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имена исходных ключей с помощью итеративного обхода.

4. Проверьте тип значений исходных ключей. Для каждого существующего ключа должно вернуться значение string.

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

6. Выполните нужную команду:

   • AND, OR или XOR
   • NOT

   1
   BITOP <операция> <имя целевого ключа> <имя ключа 1> <имя ключа 2> [<имя ключа 3> ...]

   В команде <операция> — это:

   • AND для логического И;
   • OR для ИЛИ;
   • XOR для исключающего ИЛИ.

   1
   BITOP NOT <имя целевого ключа> <имя исходного ключа>

   Операция NOT инвертирует биты. Для нее укажите ровно один исходный ключ.

   При ненулевой длине результата команда сохранит его как строку. В ответе вернется длина результата в байтах. Если все исходные строки пусты или отсутствуют, вернется 0, а целевой ключ будет удален. Для AND, OR и XOR результат будет иметь длину самой длинной исходной строки, недостающие байты более коротких строк будут учтены как нулевые. Несуществующие исходные ключи будут учтены как пустые строки. При разных исходных и целевом именах исходные значения сохранятся.

Чтобы записать целое число в битовое поле или изменить его на заданный шаг, используйте команду BITFIELD.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

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

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение string.

5. Выберите тип и смещение поля.

6. Выполните нужную команду:

   • Записать значение
   • Изменить значение

   1
   BITFIELD <имя ключа> SET <тип поля> <смещение> <значение>

   Команда запишет число и вернет список с предыдущим значением поля. Задайте число, которое помещается в выбранный тип поля.

   1
   BITFIELD <имя ключа> [OVERFLOW WRAP | OVERFLOW SAT | OVERFLOW FAIL] INCRBY <тип поля> <смещение> <шаг>

   В команде:

   • <шаг> — целое число. Отрицательное значение уменьшит поле.
   • WRAP — при переполнении перейти через границу диапазона. Этот режим будет использован по умолчанию.
   • SAT — ограничить результат ближайшей границей диапазона.
   • FAIL — при переполнении не изменять поле и вернуть nil для этой операции.

   Команда вернет список с новым значением поля или nil при срабатывании FAIL.

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

   Недостающие биты будут считаться нулевыми. При записи за пределами строки она будет расширена. Для изменения полей используйте отдельный ключ, предназначенный для битовых данных.