Redis命令學習SCAN，一個基於遊標的迭代器，生產環境必備命令

SCAN cursor [MATCH pattern] [COUNT count]

SCAN 命令及其相關的 SSCAN 命令、 HSCAN 命令和 ZSCAN 命令都用於增量地迭代（incrementally iterate）一集元素（a collection of elements）：

SCAN 命令用於迭代當前資料庫中的資料庫鍵。

SSCAN 命令用於迭代集合鍵中的元素。

HSCAN 命令用於迭代雜湊鍵中的鍵值對。

ZSCAN 命令用於迭代有序集合中的元素（包括元素成員和元素分值）。

以上列出的四個命令都支援增量式迭代，它們每次執行都只會返回少量元素，所以這些命令可以用於生產環境，而不會出現像 KEYS 命令、 SMEMBERS 命令帶來的問題 —— 當 KEYS 命令被用於處理一個大的資料庫時，又或者 SMEMBERS 命令被用於處理一個大的集合鍵時，它們可能會阻塞伺服器達數秒之久。

不過，增量式迭代命令也不是沒有缺點的：舉個例子，使用 SMEMBERS 命令可以返回集合鍵當前包含的所有元素，但是對於 SCAN這類增量式迭代命令來說，因為在對鍵進行增量式迭代的過程中，鍵可能會被修改，所以增量式迭代命令只能對被返回的元素提供有限的保證（offer limited guarantees about the returned elements）。

因為 SCAN 、 SSCAN 、 HSCAN 和 ZSCAN 四個命令的工作方式都非常相似，所以這個文件會一併介紹這四個命令，但是要記住：

SSCAN 命令、 HSCAN 命令和 ZSCAN 命令的第一個引數總是一個數據庫鍵。

而 SCAN 命令則不需要在第一個引數提供任何資料庫鍵 —— 因為它迭代的是當前資料庫中的所有資料庫鍵。

SCAN 命令的基本用法

SCAN 命令是一個基於遊標的迭代器（cursor based iterator）： SCAN 命令每次被呼叫之後，都會向用戶返回一個新的遊標，使用者在下次迭代時需要使用這個新遊標作為 SCAN 命令的遊標引數，以此來延續之前的迭代過程。

當 SCAN 命令的遊標引數被設定為 0 時，伺服器將開始一次新的迭代，而當伺服器向用戶返回值為 0 的遊標時，表示迭代已結束。

以下是一個 SCAN 命令的迭代過程示例：

redis 127。0。0。1：6379> scan 01） “17”2） 1） “key：12” 2） “key：8” 3） “key：4” 4） “key：14” 5） “key：16” 6） “key：17” 7） “key：15” 8） “key：10” 9） “key：3” 10） “key：7” 11） “key：1”redis 127。0。0。1：6379> scan 171） “0”2） 1） “key：5” 2） “key：18” 3） “key：0” 4） “key：2” 5） “key：19” 6） “key：13” 7） “key：6” 8） “key：9” 9） “key：11”

在上面這個例子中，第一次迭代使用 0 作為遊標，表示開始一次新的迭代。

第二次迭代使用的是第一次迭代時返回的遊標，也即是命令回覆第一個元素的值 —— 17 。

從上面的示例可以看到， SCAN 命令的回覆是一個包含兩個元素的陣列，第一個陣列元素是用於進行下一次迭代的新遊標，而第二個陣列元素則是一個數組，這個陣列中包含了所有被迭代的元素。

在第二次呼叫 SCAN 命令時，命令返回了遊標 0 ，這表示迭代已經結束，整個資料集（collection）已經被完整遍歷過了。

以 0 作為遊標開始一次新的迭代，一直呼叫 SCAN 命令，直到命令返回遊標 0 ，我們稱這個過程為一次

完整遍歷

（full iteration）。

SCAN 命令的保證（guarantees）

SCAN 命令，以及其他增量式迭代命令，在進行完整遍歷的情況下可以為使用者帶來以下保證：從完整遍歷開始直到完整遍歷結束期間，一直存在於資料集內的所有元素都會被完整遍歷返回；這意味著，如果有一個元素，它從遍歷開始直到遍歷結束期間都存在於被遍歷的資料集當中，那麼 SCAN 命令總會在某次迭代中將這個元素返回給使用者。

然而因為增量式命令僅僅使用遊標來記錄迭代狀態，所以這些命令帶有以下缺點：

同一個元素可能會被返回多次。處理重複元素的工作交由應用程式負責，比如說，可以考慮將迭代返回的元素僅僅用於可以安全地重複執行多次的操作上。

如果一個元素是在迭代過程中被新增到資料集的，又或者是在迭代過程中從資料集中被刪除的，那麼這個元素可能會被返回，也可能不會，這是未定義的（undefined）。

SCAN 命令每次執行返回的元素數量

增量式迭代命令並不保證每次執行都返回某個給定數量的元素。

增量式命令甚至可能會返回零個元素，但只要命令返回的遊標不是 0 ，應用程式就不應該將迭代視作結束。

不過命令返回的元素數量總是符合一定規則的，在實際中：

對於一個大資料集來說，增量式迭代命令每次最多可能會返回數十個元素；

而對於一個足夠小的資料集來說，如果這個資料集的底層表示為編碼資料結構（encoded data structure，適用於是小集合鍵、小雜湊鍵和小有序集合鍵），那麼增量迭代命令將在一次呼叫中返回資料集中的所有元素。

最後，使用者可以透過增量式迭代命令提供的 COUNT 選項來指定每次迭代返回元素的最大值。

COUNT 選項

雖然增量式迭代命令不保證每次迭代所返回的元素數量，但我們可以使用 COUNT 選項，對命令的行為進行一定程度上的調整。

基本上， COUNT 選項的作用就是讓使用者告知迭代命令，在每次迭代中應該從資料集裡返回多少元素。

雖然 COUNT 選項

只是對增量式迭代命令的一種提示

（hint），但是在大多數情況下，這種提示都是有效的。

COUNT 引數的預設值為 10 。

在迭代一個足夠大的、由雜湊表實現的資料庫、集合鍵、雜湊鍵或者有序集合鍵時，如果使用者沒有使用 MATCH 選項，那麼命令返回的元素數量通常和 COUNT 選項指定的一樣，或者比 COUNT 選項指定的數量稍多一些。

在迭代一個編碼為整數集合（intset，一個只由整數值構成的小集合）、或者編碼為壓縮列表（ziplist，由不同值構成的一個小雜湊或者一個小有序集合）時，增量式迭代命令通常會無視 COUNT 選項指定的值，在第一次迭代就將資料集包含的所有元素都返回給使用者。

並非每次迭代都要使用相同的

COUNT

值。

使用者可以在每次迭代中按自己的需要隨意改變 COUNT 值，只要記得將上次迭代返回的遊標用到下次迭代裡面就可以了。

MATCH 選項

和 KEYS 命令一樣，增量式迭代命令也可以透過提供一個 glob 風格的模式引數，讓命令只返回和給定模式相匹配的元素，這一點可以透過在執行增量式迭代命令時，透過給定 MATCH 引數來實現。

以下是一個使用 MATCH 選項進行迭代的示例：

redis 127。0。0。1：6379> sadd myset 1 2 3 foo foobar feelsgood（integer） 6redis 127。0。0。1：6379> sscan myset 0 match f*1） “0”2） 1） “foo” 2） “feelsgood” 3） “foobar”

需要注意的是，對元素的模式匹配工作是在命令從資料集中取出元素之後，向客戶端返回元素之前的這段時間內進行的，所以如果被迭代的資料集中只有少量元素和模式相匹配，那麼迭代命令或許會在多次執行中都不返回任何元素。

以下是這種情況的一個例子：

redis 127。0。0。1：6379> scan 0 MATCH *11*1） “288”2） 1） “key：911”redis 127。0。0。1：6379> scan 288 MATCH *11*1） “224”2）（empty list or set）redis 127。0。0。1：6379> scan 224 MATCH *11*1） “80”2）（empty list or set）redis 127。0。0。1：6379> scan 80 MATCH *11*1） “176”2）（empty list or set）redis 127。0。0。1：6379> scan 176 MATCH *11* COUNT 10001） “0”2） 1） “key：611” 2） “key：711” 3） “key：118” 4） “key：117” 5） “key：311” 6） “key：112” 7） “key：111” 8） “key：110” 9） “key：113” 10） “key：211” 11） “key：411” 12） “key：115” 13） “key：116” 14） “key：114” 15） “key：119” 16） “key：811” 17） “key：511” 18） “key：11”

如你所見，以上的大部分迭代都不返回任何元素。

在最後一次迭代，我們透過將 COUNT 選項的引數設定為 1000 ，強制命令為本次迭代掃描更多元素，從而使得命令返回的元素也變多了。

併發執行多個迭代

在同一時間，可以有任意多個客戶端對同一資料集進行迭代，客戶端每次執行迭代都需要傳入一個遊標，並在迭代執行之後獲得一個新的遊標，而這個遊標就包含了迭代的所有狀態，因此，伺服器無須為迭代記錄任何狀態。

中途停止迭代

因為迭代的所有狀態都儲存在遊標裡面，而伺服器無須為迭代儲存任何狀態，所以客戶端可以在中途停止一個迭代，而無須對伺服器進行任何通知。

即使有任意數量的迭代在中途停止，也不會產生任何問題。

使用錯誤的遊標進行增量式迭代

使用間斷的（broken）、負數、超出範圍或者其他非正常的遊標來執行增量式迭代並不會造成伺服器崩潰，但可能會讓命令產生未定義的行為。

未定義行為指的是，增量式命令對返回值所做的保證可能會不再為真。

只有兩種遊標是合法的：

在開始一個新的迭代時，遊標必須為 0 。