> For the complete documentation index, see [llms.txt](https://aiii-mike.gitbook.io/redis/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aiii-mike.gitbook.io/redis/command/hash/hscan.md).

# hscan

### 1. 基本語法

#### hscan**(`hkey`,  `cursor`, `['MATCH', pattern]`, `['COUNT', count]`,`callback`)** 

針對**`hkey`**資料進行漸進式的[遍歷(**Traversal**)](https://zh.wikipedia.org/wiki/%E6%A0%91%E7%9A%84%E9%81%8D%E5%8E%86)取值，透過**`MATCH`**參數篩選欄位(Sub-Key)資料，該指令**不保證**回傳的鍵值對(Sub-Key : Value)數量，但可透過**`COUNT`**制定最少的回傳數目，並透過新的**`cursor`**來取得下一群資料內容，當**`cursor`**等於**'0'**時，代表遍歷已結束。

| Parameter     | Default  |
| ------------- | -------- |
| **`pattern`** | **'\*'** |
| **`count`**   | **'10'** |

{% hint style="info" %}
以下兩者任一成立時，**`COUNT`**參數才會發會作用。

* 當**`hkey`**中的鍵值對(**Sub-Key** : **Value**)數量超過512的時候。
* 當**`hkey`**中任意一個欄位(**Sub-Key**)對應的資料(**Value**)長度超過64。
  {% endhint %}

### 2. 範例

#### (1) 預設參數會試圖取得所有**`hkey`**資料

若**`hkey`**對應欄位(**Sub-Key**)過多，則先回傳部分資料及非零**cursor**，並得以透過新**cursor**取得下一組**`hkey`**資料

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const dict = { 
    name: 'John Miller', 
    gender: 'M', 
    age: '34',
    hobby1 : 'Whistle',
    hobby2 : 'War',
    hobby3 : 'Walk'
};

client.hmset('user:5', dict);

let cursor = '0';
client.hscan('user:5', cursor , (err, scanner) => {
    cursor = scanner[0];
    let kv_list = scanner[1];
    console.log('Cursor:', cursor);
    console.log('Data:', kv_list);
});
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Output-TS" %}

```
Cursor: 0
Data: [
  'name',   'John Miller',
  'gender', 'M',
  'age',    '34',
  'hobby1', 'Whistle',
  'hobby2', 'War',
  'hobby3', 'Walk'
]
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
注意回傳結果為Array形式
{% endhint %}

#### (2) 模糊篩選subkey

{% tabs %}
{% tab title="TypeScript" %}

```typescript
let cursor = '0';
client.hscan('user:5', cursor, 'MATCH', 'hobby*', 'COUNT', '10', 
    (err, scanner) => {
        let cursor = scanner[0];
        let kv_list = scanner[1];
        console.log('Next Cursor:', cursor);
        console.log('Cuurent Data:', kv_list);
    }
);
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Output-TS" %}

```
Cursor: 0
Data: [ 'hobby1', 'Whistle', 'hobby2', 'War', 'hobby3', 'Walk' ]
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aiii-mike.gitbook.io/redis/command/hash/hscan.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.