Amazon Redshift 將不再支援從修補程式 198 開始建立新的 Python UDFs。現有 Python UDF 將繼續正常運作至 2026 年 6 月 30 日。如需詳細資訊，請參閱[部落格文章](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# ARRAY\$1POSITION 函數
<a name="array_position"></a>

傳回陣列中第一次出現指定元素的位置 （索引）。索引以 0 為基礎，其中 0 表示第一個元素，1 表示第二個元素，以此類推。如果在陣列中找不到 元素，則傳回 -1。

函數只會傳回第一次出現的位置。若要尋找所有出現的項目，請考慮使用 [ARRAY\$1POSITIONS 函數](array_positions.md)函數。

## 語法
<a name="array_position-syntax"></a>

```
ARRAY_POSITION( array, value [, null_match] )
```

## 引數
<a name="array_position-arguments"></a>

 *陣列*   
SUPER 表達式，指定要在其中搜尋的陣列。

 *value*   
指定要搜尋之元素的值。

 *null\$1match*   
布林值，指定 NULL 值的處理方式：  
+ *null\$1match* = FALSE：搜尋 NULL 會傳回 NULL。如果陣列包含 NULL 值，且找不到非 NULL 搜尋值的相符項目，則 會傳回 NULL。
+ *null\$1match* = TRUE：NULLs 視為有效的可搜尋元素。如果陣列包含 NULL 值，但找不到非 NULL 搜尋值的相符項目，則會傳回 -1。
預設值為 TRUE。  
組態選項也可以指定預設 NULL 處理：  

```
-- same as null_match = TRUE
SET default_array_search_null_handling to TRUE;
```

## 傳回類型
<a name="array_position-return-type"></a>

ARRAY\$1POSITION 函數會傳回 INT 類型。

## 範例
<a name="array_position-example"></a>

下列範例顯示 ARRAY\$1POSITION 函數。

```
SELECT ARRAY_POSITION(ARRAY('red', 'green'), 'red');
 array_position 
----------------
              0
(1 row)

SELECT ARRAY_POSITION(ARRAY(1, 2, 3), 4);
 array_position 
----------------
             -1
(1 row)

-- only the position of the first occurrence is returned
SELECT ARRAY_POSITION(ARRAY('red', 'green', 'red'), 'red');
 array_position 
----------------
              0
(1 row)
```

下列範例顯示將 *null\$1match* 設定為 TRUE 的函數行為。

```
SET default_array_search_null_handling to TRUE;

-- NULL search is enabled
SELECT ARRAY_POSITION(ARRAY('red', NULL, 'green'), NULL);
 array_position 
----------------
              1
(1 row)

-- The array can contain NULLs
SELECT ARRAY_POSITION(ARRAY('red', NULL, 'green'), 'blue', TRUE);
 array_position 
----------------
             -1
(1 row)
```

下列範例顯示將 *null\$1match* 設定為 FALSE 的函數行為。請注意，在函數中指定 *null\$1match* 行為會覆寫預設組態設定。

```
-- same as null_match = TRUE
SET default_array_search_null_handling to TRUE;

-- NULL search is disabled. The default behavior is overridden
SELECT ARRAY_POSITION(ARRAY('red', 'green'), NULL, FALSE);
 array_position 
----------------
               
(1 row)

-- same as null_match = FALSE
SET default_array_search_null_handling to FALSE;

-- The array contains NULL and a match is found
SELECT ARRAY_POSITION(ARRAY('red', NULL, 'green'), 'green');
 array_position 
----------------
              2
(1 row)

-- The array contains NULL but no match is found
SELECT ARRAY_POSITION(ARRAY('red', NULL, 'green'), 'blue');
 array_position 
----------------
               
(1 row)
```

## 另請參閱
<a name="array_position-see-also"></a>
+ [ARRAY\$1POSITIONS 函數](array_positions.md)
+ [ARRAY\$1CONTAINS 函數](array_contains.md)
+ [SUBARRAY 函數](r_subarray.md)