API

TODO: снапшот параметры и методы Все методы работают с конкретным префиксом, который нужно указывать в поле prefix. Нет методов, которые работают сразу с несколькими префиксами. Префикс должен быть совместим с файловой системой linux. По сути это имя директории хранилища. Желательно чтобы он не требовал экранирования json, а в идеале только латинские буквы, цифры, "_" и ".".

У всех методов, за исключением range, есть параметр fields. У методов get, has и del - это массив ключей. У метода set ассоциативный массив (объект) с фактическими значениями, у остальных inc, add и packed - ассоциативный массив с параметрами обновления.

Все модифицирующие методы имеют параметр sync, который по умолчанию отключен. Его допустимо использовать только для критически важных данных, которым в принципе тут не место - это влияет на производительность. При штатном перезапуске, и в большинстве аварийных случаев (за исключением отключения питания), данные будут сохранены. Более вероятна ситуация когда демон упадет в момент обработки запроса, а тут никакие sync не помогут. И с учетом того, что пока еще его уронить не получилось, то забудьте про него.

Кроме того, все модифицирующие методы могут возвращать значения измененных ключей. Эти параметры так-же по умолчанию отключены ( флаги nores=true и noval=true) из-за соображений производительности. Более подробное описание в смотрите для каждого метода.

У всех методов в ответе есть поле status, которое принимает значение "OK" случае успешного выполнения операции. Если нужно проверить прошла операция или нет, то проверяем только это поле. Этого достаточно. Не нужно отключать nores и noval у модифицирующих операций, чтобы потом проверять, что-же там записалось. В этом нет никакого смысла. Все методы пишут пакетно, поэтому срабатывает все или ничего.

Ограничения

Прописаны в конфиги и накладывают ограничения на размер ключа, значений и пр. Значения по умолчанию:

prefix_size_limit = 256 - максимальная длинна префикса
key_size_limit = 128 - максимальная длинна ключа
value_size_limit = 10240 - максимальная длинна значения
keys_per_req = 100 - максимальное количество ключей в запросе
max_prefixes = 128 - максимально допустимое количество префиксов
packed_limit = 1000 - максимальное количество элементов при пакетном обновлении (packed )
array_limit = 1000 - максимально допустимые размер циклического массива (add )

set, setnx - записать данные по ключам
get - получить данные по ключам
del - удалить по ключам
has - проверить наличие по по ключам
inc - увеличить(уменьшить) значения полей
add - добавить элементы в циклический массив
packed - пакетное обновление
range - работа с диапазонами

Метод set, setnx

Установка значений для нескольких ключей. Значение ключа - произвольный json-объект, строка, число или флаг. Объект сохраняется в базу как есть, без десериализации, в таком же виде и возвращается при запросе.

setnx - вариант метода set, но работает только если ключ новый. Для существующих в базе ключей запись игнорируется и возвращается старое значение (если задан noval=true). Реализован с использованием механизма мерджинга (см. примечание в inc)

запрос (set)

{
  "prefix":"префикс",
  "nores":true,
  "noval":false,
  "sync" :false,
  "fields":
    {
      "ключ1":json,
      "ключ2":json,
      "ключ3":json
    }
}

prefix - имя префикса
sync - синхронная запись на диск (без кэширования). Использовать только для реально критичных данных
nores - если true(по умолчанию), то пустой результат в ответе. Используется когда нужно дождаться ответа, но результат не важен. Если задан, то noval игнорируется
noval - по умолчанию false. Если задан, то возвращает true или false вместо значения поля, в зависимости от того существует поле или нет
fields - объект, ассоциативный массив полей для записи

Если нужно получить в ответе значения записанных полей (например для тестирования, в бою это не нужно), то используете nores=false и noval=false. В этом случае после записи будет произведен полноценный get из хранилища, что замедляет работу демона. Внимание!!! Не использовать для проверки того, записалось ли конкретное поля в базу или нет! Если в результате status==OK то все гарантированно записалось! Если в ответе не нужны значения, установите noval=true - в место значений будут флаги: true если поле существует и false в противном случае. Внимание!!! Это также не использовать для проверки записи. Значение false может быть только когда между записью и вызовом get для формирования результата, поле было удалено. Описанные возможности допустимо использовать только на этапах разработки и тестирования.

ответ (set)

{
  "prefix":"префикс",
  "status":"OK",
  "fields":{
    "ключ1":json,
    "ключ2":json,
    "ключ3":json
  }
}

prefix имя префикса или пустая строка (для nores==true)
status - результат запроса
- OK - OK
- WriteError - ошибка записи
- CreatePrefixFail - ошибка создания префикса
fields - в зависимости от параметров запроса пустой объект, объект ключ-json или ключ-флаг

Метод get

Возвращает значения нескольких ключей.

запрос (get)

{
  "prefix":"префикс",
  "fields":["ключ1","ключ2","ключ3"]
}

prefix - имя префикса
fields - массив ключей

ответ (get)

{
  "prefix":"префикс",
  "status":"OK",
  "fields":{
    "ключ1":json,
    "ключ2":json,
    "ключ3":json
  }
}

prefix - имя префикса
status - результат запроса
- OK - OK
- PrefixNotFound - префикс не существует
fields - объект, ассоциативный массив ключ/значения. Если ключа нет, то возвращает "null".

Примечание. Можно записать в поле null, но понять, что оно существует используя это метод не получится. Чтобы точно определить существует поле или нет используйте метод has.

Метод has

Проверка на существования набора ключей.

запрос (has)

{
  "prefix":"префикс",
  "fields":["ключ1","ключ2","ключ3"]
}

prefix - имя префикса
fields - массив ключей

ответ (has)

{
  "prefix":"префикс",
  "status":"OK",
  "fields":{
    "ключ1":true,
    "ключ2":true,
    "ключ3":false
  }
}

prefix - имя префикса
status - результат запроса
- OK - OK
- PrefixNotFound - префикс не существует
fields - объект, ассоциативный массив ключ/флаг ( true или false ).

Метод del

Удаление набора ключей

запрос (del)

{
  "prefix":"префикс",
  "sync" :false,
  "nores":true,
  "noval":true,
  "fields":["ключ1","ключ2","ключ3"]
}

prefix - имя префикса
sync - синхронное удаление с диска. Использовать только для реально критичных данных.
nores - если true(по умолчанию), то пустой результат в ответе. Используется для получение значений удаляемых данных.
noval - по умолчанию false. Используется для получение флагов существования удаляемых полей.
fields - объект, ассоциативный массив полей для записи

Примечание. Механизм работы nores и noval такой-же как и у set В бою использовать можно, но только там, где реально необходимо получить удаляемые данные. Обратите внимание, что комбинация nores=true и noval=false дает объект ассоциативный массив флагов существующих до удаления объектов, а не флаг того, что ключ реально удален.

ответ (del)

{
  "prefix":"префикс",
  "status":"OK",
  "fields":{
    "ключ1":json,
    "ключ2":json,
    "ключ3":json
  }
}

prefix имя префикса или пустая строка (для nores==true)
status - результат запроса
- OK - OK
- WriteError - ошибка записи
- PrefixNotFound - префикс не существует
fields - в зависимости от параметров запроса пустой объект, объект ключ-json или ключ-флаг

Метод inc

Увеличивает или уменьшает значения набора ключей целочисленного типа на заданное значение. Если ключа не существует или оно не числового типа, то записывается значение по умолчанию. Внимание! Читайте примечание!

запрос (inc)

{
  "prefix":"префикс",
  "sync" :false,
  "nores":true,
  "update":
    {
      "ключ1":{"inc":1, "val":0},
      "ключ2":{"inc":-1, "val":100},
      "ключ3":{"inc":10, "val":-100}
    }
}

prefix - имя префикса
sync - синхронная запись запроса на диск
nores - если true(по умолчанию), то пустой результат в ответе. Используется для получение значений после операции инкремента.
fields - объект, ассоциативный массив полей для записи

ответ (inc)

{
  "prefix":"префикс",
  "status":"OK",
  "fields":{
    "ключ1":0,
    "ключ2":100,
    "ключ3":-100
  }
}

prefix - имя префикса или пустая строка (для nores==true)
status - результат запроса
- OK - OK
- PrefixNotFound - префикс не существует
fields - в зависимости от параметров запроса пустой объект или объект ключ-число. Возможно в качестве значения ключа получить null или не числовой объект, если после инкремента из другого потока ключ был удален или изменен.

Примечание. Для этого метода используется специфичная для rocksdb операция мерджинга. В leveldb, для аналогичной операции, для каждого ключа блокировался мьютекс из пула (это 0.1% всех счетчиков), производилось чтение, изменялось значение, производилось запись и снималась блокирока. С использованием мерджинга мы избавляемся не только от блокировок, но и от лишних операций чтения/записи. Фактически все операции производятся отложено при Get-запросах. Например, если было 10 операций инкремента, то все они записываются в специальный лог на диск. При запросе, отрабатываются все десять инкрементов последовательно и производиться запись результата - это хорошо влияет на общую производительность. Выключая nores вы также частично теряете и эту оптимизацию, так как сразу после записи запроса, для получения результата, производится Get-запрос который запускает механизм мерждинга.

Метод add

Добавляет произвольные объекты в циклический массив (Round-robin) заданного размера. Если исходное значение ключа не является массивом, то оно удаляется.

запрос (add)

{
  "prefix":"префикс",
  "sync" :false,
  "nores":true,
  "noval":true,
  "update":{
    "ключ1":{"lim":10, "arr":[1,2]},
    "ключ2":{"lim":0, "arr":[]}
  }
}

prefix - имя префикса
sync - синхронная запись операции на диск. Использовать только для реально критичных данных.
nores - если true(по умолчанию), то пустой результат в ответе. Используется для получение значений обновленных данных.
noval - по умолчанию false. Используется для получение флагов вместо значений полей.
update - объект, ассоциативный массив ключей с параметрами обновления:
- lim - ограничение на размер массива. Если происходит превышение, то удаляются значения из головы массива
- arr - массив значений, которые будут добавлены в конец исходного массива
- Для очистки массива lim=0, для удаления используете get

ответ (add)

{
  "prefix":"префикс",
  "status":"OK",
  "fields":{
    "ключ1":[1,2],
    "ключ2":[]
  }
}

prefix - имя префикса или пустая строка (для nores==true)
status - результат запроса
- OK - OK
- PrefixNotFound - префикс не существует
fields - в зависимости от параметров запроса пустой объект, объект ассоциативный массив флагов или значений. В последнем варианте значением также будет ассоциативный массив с обновленными значениями.

Примечание. Для этого метода также задействован механизм мерждинга. Читай примечание метода inc.

Метод packed

Пакетное обновление json-объектов (ассоциативных массивов). Если ключа не существует или типом значения не json-объект, то такой объект создается. Доступны операции изменения, удаления и инкремента.

запрос (packed)

{
  "prefix":"префикс",
  "sync" :false,
  "nores":true,
  "noval":true,
  "update":{
    "ключ1":{
       "k1":{"inc":1, "val":0},
       "k2":{"inc":null, "val":[1,2,3]},
       "k3":{"inc":null, "val":null}
    }
  }
}

prefix - имя префикса или пустая строка (для nores==true)
sync - синхронная запись операции на диск. Использовать только для реально критичных данных.
nores - если true(по умолчанию), то пустой результат в ответе. Используется для получение значений обновленных данных.
noval - по умолчанию false. Используется для получение флагов вместо значений полей.
update - объект, ассоциативный массив ключей с параметрами обновления:
- inc - если не null, то это операция инкремента, а в val стартовое значение (если ключа не существует). Если в val не число, то значение val игнорируется, а стартовым значением будет ноль. Если ключ существует и не числового типа, то он замещается стартовым значением
- val - новое значение поля поля, если "inc":null
- Для удаление поля {"inc":null, "val":null}

Примечание. Для этого метода также задействован механизм мерждинга. Читай примечание метода inc. По примеру:

k1 - инкремент поля
k2 - новое значение поля
k3 - удаление ключа

ответ (packed)

{
  "prefix":"префикс",
  "status":"OK",
  "fields":{
    "ключ1":{
       "k1":0,
       "k2":[1,2,3]
    }
  }
}

prefix - имя префикса
status - результат запроса
- OK - OK
- PrefixNotFound - префикс не существует
fields - в зависимости от параметров запроса пустой объект, объект ассоциативный массив флагов или объектов. В последнем варианте значением также будет ассоциативный массив с обновленными значениями.

Примечание. Если по примеру выше, сделать запрос get для ключ1, то результатом будет {"k1":0,"k2":[1,2,3]}

Метод range

Запрос диапазона счетчиков.

запрос (range)

{
  "prefix":"префикс",
  "from":"ключ1",
  "to":"ключ2",
  "offset":0,
  "limit":10
}

prefix - имя префикса
from - начальный ключ. Пустая строка если с начала.
to - последний ключ. Пустая строка если до конца.
offset - смещение относительно from
limit - максимальное количество полей в результате
noval - в место значений возвращать пустые строки "". Используется, если значения полей не интересны.

ответ (range)

{
  "prefix":"префикс",
  "status":"OK",
  "final":true,
  "fields":{
    "ключ1":json,
    "ключ2":json,
    "ключ3":json
  }
}

prefix - имя префикса
final - конец диапазона, больше нет ключей. Позволяет избежать лишний запрос.
status - результат запроса
- OK - OK
- PrefixNotFound - префикс не существует
fields - объект, ассоциативный массив ключ/значения.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

api.md

api.md

API

Ограничения

Метод set, setnx

запрос (set)

ответ (set)

Метод get

запрос (get)

ответ (get)

Метод has

запрос (has)

ответ (has)

Метод del

запрос (del)

ответ (del)

Метод inc

запрос (inc)

ответ (inc)

Метод add

запрос (add)

ответ (add)

Метод packed

запрос (packed)

ответ (packed)

Метод range

запрос (range)

ответ (range)

Files

api.md

Latest commit

History

api.md

File metadata and controls

API

Ограничения

Метод set, setnx

запрос (set)

ответ (set)

Метод get

запрос (get)

ответ (get)

Метод has

запрос (has)

ответ (has)

Метод del

запрос (del)

ответ (del)

Метод inc

запрос (inc)

ответ (inc)

Метод add

запрос (add)

ответ (add)

Метод packed

запрос (packed)

ответ (packed)

Метод range

запрос (range)

ответ (range)