Перейти к содержимому

Операции с ключами

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

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

Проверить существование ключа

Заголовок раздела «Проверить существование ключа»

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

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

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

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

    text
    EXISTS <имя ключа 1> [<имя ключа 2> ...]

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

Получить тип значения

Заголовок раздела «Получить тип значения»

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

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

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

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

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

    text
    TYPE <имя ключа>

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

Переименовать ключ

Заголовок раздела «Переименовать ключ»

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

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

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

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

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

    text
    RENAME <имя ключа> <новое имя ключа>

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

Переместить ключ в другую базу данных

Заголовок раздела «Переместить ключ в другую базу данных»

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

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

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

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

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

    text
    MOVE <имя ключа> <номер базы данных>

    В команде <номер базы данных> — номер целевой базы данных, отличный от номера текущей базы. Допустимые номера — от 0 до N-1, где N — количество баз данных, заданное параметром databases.

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

Скопировать ключ

Заголовок раздела «Скопировать ключ»

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

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

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

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

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

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

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

    text
    COPY <имя исходного ключа> <имя целевого ключа> [DB <номер базы данных>] [REPLACE]

    В команде:

    • DB <номер базы данных> — скопировать значение в указанную базу данных того же кластера. Если параметр не указан, будет использована текущая база данных.

      Допустимые номера базы данных — от 0 до N-1, где N — количество баз данных, заданное параметром databases.

    • REPLACE — перезаписать целевой ключ, если он существует.

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

    Команда скопирует значение и вернет 1. Исходный ключ сохранится. Если исходный ключ не существует или целевой ключ существует, но параметр REPLACE не указан, команда вернет 0 и не создаст копию.

Найти ключи по шаблону

Заголовок раздела «Найти ключи по шаблону»

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

Внимание

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

Для использования команды KEYS у пользователя должны быть права на ее выполнение или выполнение команд категории dangerous.

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

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

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

    text
    KEYS <шаблон>

    В команде <шаблон> — шаблон имени ключа. Например:

    • user:* — имена, которые начинаются с user:;
    • user:? — имена, в которых после user: указан один символ;
    • user:[ab] — имена user:a и user:b.

    Шаблон * подойдет для всех ключей в текущей базе данных.

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

Итеративно обойти ключи

Заголовок раздела «Итеративно обойти ключи»

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

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

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

  3. Начните обход с курсора 0:

    text
    SCAN 0 [MATCH <шаблон>] [COUNT <количество>] [TYPE <тип>]

    В команде:

    • MATCH <шаблон> — отобрать имена по шаблону.
    • COUNT <количество> — задать ориентир объема работы за один вызов, положительное целое число. Это не ограничение количества результатов.
    • TYPE <тип> — отобрать ключи по типу значения, например hash.

    Команда вернет следующий курсор и список найденных ключей.

  4. Подставляйте полученный курсор в следующий вызов, сохраняя условия отбора:

    text
    SCAN <курсор> [MATCH <шаблон>] [COUNT <количество>] [TYPE <тип>]

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

Получить случайный ключ

Заголовок раздела «Получить случайный ключ»

Чтобы получить имя случайного ключа, используйте команду RANDOMKEY.

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

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

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

    text
    RANDOMKEY

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

Сериализовать и восстановить значение

Заголовок раздела «Сериализовать и восстановить значение»

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

  • DUMP — получить сериализованное значение;
  • RESTORE — создать ключ из сериализованного значения.

Для использования команды RESTORE у пользователя должны быть права на ее выполнение или выполнение команд категории dangerous.

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

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

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

  4. Получите сериализованное значение:

    text
    DUMP <имя исходного ключа>

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

  5. Подготовьте полученное значение к передаче в RESTORE без изменения байтов.

  6. Выберите срок жизни целевого ключа. Для ключа без срока жизни используйте 0.

    DUMP не сохранит срок жизни исходного ключа. Если нужно задать срок на основе исходного ключа, узнайте его оставшееся время в текущей базе данных. Положительный ответ можно использовать как новый срок жизни. Он будет отсчитан с момента восстановления, и исходный момент истечения не сохранится. Для ключа без срока жизни при ответе -1, используйте 0. При ответе -2 или 0 исходный ключ уже отсутствует или его срок заканчивается — прекратите перенос. Раздельные вызовы DUMP и PTTL не обеспечат согласованный снимок при изменении ключа.

  7. Если нужно восстановить значение в другой базе данных, переключитесь на нее. Выполните команду:

    text
    RESTORE <имя целевого ключа> <срок жизни> <сериализованное значение> [REPLACE]

    В команде:

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

    Команда создаст целевой ключ и вернет OK. Если целевой ключ существует, но параметр REPLACE не указан, команда вернет ошибку. При поврежденных данных или несовместимом формате сериализации также вернется ошибка.

Передать результат DUMP в RESTORE через valkey-cli

Заголовок раздела «Передать результат DUMP в RESTORE через valkey-cli»

Чтобы передать бинарное значение из команды DUMP в команду RESTORE вручную, используйте интерактивный режим valkey-cli с выводом в кавычках. Правила экранирования описаны в официальной документации клиента.

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

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

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

  4. Выполните команду в интерактивном режиме valkey-cli с обычным выводом, без режима --raw:

    text
    DUMP <имя исходного ключа>

    Клиент выведет значение в двойных кавычках, а непечатаемые байты представит последовательностями вида \xHH. Если вернется nil, исходный ключ отсутствует и передавать значение не нужно.

  5. Скопируйте полный ответ вместе с внешними двойными кавычками.

  6. Подставьте скопированный ответ вместо сериализованного значения в команду RESTORE. Выполняйте команду в интерактивном valkey-cli, а не в командной оболочке операционной системы.

    valkey-cli преобразует экранированную строку в исходные байты и передаст ее серверу как один аргумент. Результат восстановления будет определяться параметрами RESTORE.

Удалить ключ

Заголовок раздела «Удалить ключ»

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

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

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

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

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

    text
    DEL <имя ключа 1> [<имя ключа 2> ...]

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