{"action":"opened","issue":{"url":"https://api.github.com/repos/tarantool/memcached/issues/3","labels_url":"https://api.github.com/repos/tarantool/memcached/issues/3/labels{/name}","comments_url":"https://api.github.com/repos/tarantool/memcached/issues/3/comments","events_url":"https://api.github.com/repos/tarantool/memcached/issues/3/events","html_url":"https://github.com/tarantool/memcached/issues/3","id":108340041,"number":3,"title":"Memcached range operation","user":{"login":"bigbes","id":495636,"avatar_url":"https://avatars.githubusercontent.com/u/495636?v=3","gravatar_id":"","url":"https://api.github.com/users/bigbes","html_url":"https://github.com/bigbes","followers_url":"https://api.github.com/users/bigbes/followers","following_url":"https://api.github.com/users/bigbes/following{/other_user}","gists_url":"https://api.github.com/users/bigbes/gists{/gist_id}","starred_url":"https://api.github.com/users/bigbes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bigbes/subscriptions","organizations_url":"https://api.github.com/users/bigbes/orgs","repos_url":"https://api.github.com/users/bigbes/repos","events_url":"https://api.github.com/users/bigbes/events{/privacy}","received_events_url":"https://api.github.com/users/bigbes/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-09-25T14:45:22Z","updated_at":"2015-09-25T14:45:22Z","closed_at":null,"body":"# Overview\r\n\r\nSeveral implementations of servers speaking the memcached protocol have backends that allow for inexpensive operations over ranges of keys. The purpose of this document is to standardize the protocol for making use of these operations.\r\n\r\n# General Properties of Range Commands\r\n\r\nCommands that take ranges all follow the same pattern of key representation. Each range representation will have a minimum and maximum range as well as flags to indicate whether each end is inclusive or exclusive. Either end may be null indicating there's no limit on the side where the null appears. Keys should be treated as byte arrays for range comparisons. The implementation is not expected to perform any type of character conversion or collation.\r\n\r\n## Abstract Representation of Ranges\r\n\r\n* `null` :: means that left/right border is end/begin respectively;\r\n* `[`/`]` :: means that left/right border respectively is included;\r\n* `(`/`)` :: means that left/right border respectively is not included;\r\n\r\n## Binary Protocol Generalities\r\n\r\n### Request\r\n\r\nIn the binary protocol, we've got some extra space and can apply that to defining ranges.  The \"key\" field will be used as the start key. A key length of zero represents null as an empty key can't be stored. The extra info will contain the following info:\r\n\r\n```\r\n+-------------+------+\r\n| Fields      |\tSize |\r\n+-------------+------+\r\n| End key len | 16   |\r\n| Reserved\t  | 8    |\r\n| Flags\t      | 8    |\r\n| Max results | 32   |\r\n+-------------+------+\r\n```\r\n\r\nFlags is a bitmask indicating whether the ends are inclusive or exclusive.\r\n\r\n* `(flags & 1)` :: If non-zero, start key is inclusive.\r\n* `(flags & 2)` :: If non-zero, end key is inclusive.\r\n\r\nMax results represents the number of objects the operation is permitted to affect. A value of zero indicates there should be no limit.\r\n\r\nA server **may** enforce a maximum limit and respond with an error if the requested limit exceeds the limit enforced by the server (or is zero).\r\n\r\nThe end key immediately follows the maximum results.\r\n\r\n### Response\r\n\r\nEach requests will generally have many responses and will return similarly to the way stats works in the binary protocol. The final response will be one with an empty key. \r\nThe binary protocol allows for commands to operate in a \"quiet mode\" where most responses are quelled. No such facility is available for the text protocol as it can't be done consistently without introducing new verbs (and then can't be done safely).\r\n\r\n## Text Protocol Generalities\r\n\r\nThe general form of a range command is as follows (please see details for how this varies by command):\r\n\r\n```\r\nCMD <start inclusion> <end inclusion> <max items> <start key> [end key]\\r\\n\r\n```\r\n\r\nThe end key is optional. If not specified, it is considered null. Null is not explicitly included for the start key as there is a natural minimum of keys which can be used in its place.\r\n\r\nThe inclusion flags are either 0 or 1. If 0, the endpoint is not included. If 1, the endpoint is included.\r\n\r\nThis is different from the rget as specified in memcachedb to allow for infinite ranges.\r\n\r\n# Supported commands\r\n\r\n## get\r\n\r\nRanged get operations allow multiple key/value pairs returned for a single key request.\r\n\r\n## set\r\n\r\nRanged set operations allow for a range of **existing** items to be set to a specific value.\r\n\r\nFor example, if you have stats stored in a server with keys prefixed as `stats.` you can reset all of them in a single operation by setting (`stats.`, `stats/`) to \"0\". This range specifies everything that begins with \"stats.\" excluding \"stats.\" itself.\r\n\r\nUpon batch mutation, each modified value will receive a new distinct CAS identifier.\r\n\r\n### Binary Protocol Details\r\n\r\nEach modified value will respond as a plain set does although the key will be included in the response. The final response will contain no key.\r\n\r\nIn the case of a quiet request, no response will be given unless the command fails.\r\n\r\n### Text Protocol Details\r\n\r\nThe command for text set is rset and has the following form:\r\n\r\n```\r\nrset <start inclusion> <end inclusion> <max items> <flags> <exptime> <bytes> <start key> [end key]\\r\\n\r\n<data>\\r\\n\r\n```\r\n\r\nThe response will be similar to a gets, but with no values included. Example:\r\n\r\n```\r\nVALUE <key> <flags> 0 [<cas>]\\r\\n\r\n\\r\\n\r\n```\r\n\r\n## append\r\n\r\nRanged append will append a value to every item within a range.\r\n\r\nFor both protocols, the response will be in the form of their respective protocol-specific response in ranged set.\r\n\r\n### Text Protocol Details\r\n\r\nThe command for text append has the following structure:\r\n\r\n```\r\nrappend <start inclusion> <end inclusion> <max items> <bytes> <start key> [end key]\\r\\n\r\n<data>\\r\\n\r\n```\r\n\r\n## prepend\r\n\r\nPrepend follows the same pattern of append.\r\n\r\n## delete\r\n\r\nRanged delete will remove all values in the specified range.\r\n\r\nFor both protocols, the response will be in the form of their respective protocol-specific response in ranged set.\r\n\r\n## incr\r\n\r\nRanged incr will increment all existing keys within a range by the same amount. This follows the same patterns as existing increment with the obvious exception that it will not initialize keys since it's only modifing things that already exist.\r\n\r\n### Binary Protocol Details\r\n\r\nThe extra data includes the standard incr/decr extra data **after** the ranged extra data.\r\n\r\nThe responses will include a key and value for every modified item.\r\n\r\n### Text Protocol Details\r\n\r\nThe text command for range increment is `rincr` and is in the following form:\r\n\r\n```\r\nrincr <start inclusion> <end inclusion> <max items> <value> <start key> [end key]\\r\\n\r\n```\r\n\r\nResponses are the same as a multi-gets.\r\n\r\n## decr\r\n\r\nRanged decr follows ranged incr.\r\n\r\n# Command Reference\r\n\r\nThe following table is a quick reference to all of the commands defined herein. Commands omitted from the text column are intentional as they are not defined outside of the binary protocol.\r\n\r\n```\r\n+-----------+-------+-----------+\r\n| Command   | Bin   | Text      |\r\n+-----------+-------+-----------+\r\n| Get\t    | 0x30\t| rget      |\r\n| Set\t    | 0x31\t| rset      |\r\n| QSet\t\t| 0x32\t|           |\r\n| Append\t| 0x33\t| rappend   |\r\n| QAppend\t| 0x34\t|           |\r\n| Prepend\t| 0x35\t| rprepend  |\r\n| QPrepend\t| 0x36\t|           |\r\n| Delete\t| 0x37\t| rdelete   |\r\n| QDelete\t| 0x38\t|           |\r\n| Incr\t\t| 0x39\t| rincr     |\r\n| QIncr\t\t| 0x3a\t|           |\r\n| Decr\t\t| 0x3b\t| rdecr     |\r\n| QDecr\t\t| 0x3c\t|           |\r\n+-----------+-------+-----------+\r\n```\r\n\r\n# Isolation\r\n\r\nIsolation levels are specifically left unspecified. Operations concurrently working on the same data set may interleave, mutually exclude each other, or just stomp all over each other.\r\n\r\nImplementors are encouraged to document their intentions.\r\n\r\n# P.S.\r\nOriginal: https://code.google.com/p/memcached/wiki/RangeOps \r\nMotive to duplicate - google source code (with project wikis) is closing."}}