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/)。

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

# 物件函數
<a name="Object_Functions"></a>

以下是 Amazon Redshift 支援在 SUPER 類型物件上建立和操作的 SQL 物件函數：

**Topics**
+ [GET\$1NUMBER\$1ATTRIBUTES 函數](get_number_attributes.md)
+ [LOWER\$1ATTRIBUTE\$1NAMES 函式](r_lower_attribute_names.md)
+ [OBJECT 函數](r_object_function.md)
+ [OBJECT\$1TRANSFORM 函數](r_object_transform_function.md)
+ [UPPER\$1ATTRIBUTE\$1NAMES 函式](r_upper_attribute_names.md)

# GET\$1NUMBER\$1ATTRIBUTES 函數
<a name="get_number_attributes"></a>

傳回字典物件根層級上有多少鍵值對存在的計數。

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

```
GET_NUMBER_ATTRIBUTES( super_expression )
```

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

 *super\$1expression*   
字典形式的 SUPER 表達式。

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

GET\$1NUMBER\$1ATTRIBUTES 函數會傳回 INT 類型。

## 注意
<a name="get_number_attributes-note"></a>

此函數只會計算直接屬性，且不包含巢狀字典中的配對。

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

下列範例顯示 GET\$1NUMBER\$1ATTRIBUTES 函數。

```
SELECT GET_NUMBER_ATTRIBUTES(JSON_PARSE('{"a": 1, "b": 2, "c": 3}'));
 get_number_attributes
-----------------------
            3
(1 row)
```

GET\$1NUMBER\$1ATTRIBUTES 函數只會在字典的第一個層級運作。

```
SELECT GET_NUMBER_ATTRIBUTES(JSON_PARSE('{"a": 1, "b": {"c": 3}}'));
 get_number_attributes
-----------------------
            2
(1 row)
```

# LOWER\$1ATTRIBUTE\$1NAMES 函式
<a name="r_lower_attribute_names"></a>

使用與 [LOWER 函數](r_LOWER.md) 相同的大小寫轉換常式，將 SUPER 值中所有適用的屬性名稱轉換為小寫。LOWER\$1ATTRIBUTE\$1NAMES 支援 UTF-8 多位元組字元，每個字元最多 4 個位元組。

 若要將 SUPER 屬性名稱轉換為大寫，請使用 [UPPER\$1ATTRIBUTE\$1NAMES 函式](r_upper_attribute_names.md)。

## 語法
<a name="r_lower_attribute_names-synopsis"></a>

```
LOWER_ATTRIBUTE_NAMES( super_expression )
```

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

*super\$1expression*  
SUPER 表達式。

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

`SUPER`

## 使用須知
<a name="r_lower_attribute_names-usage-notes"></a>

在 Amazon Redshift 中，欄識別碼傳統上不區分大小寫，並且會轉換為小寫。如果您從 JSON 等區分大小寫的資料格式擷取資料，則資料可能包含混合大小寫的屬性名稱。

請考量下列範例。

```
CREATE TABLE t1 (s) AS SELECT JSON_PARSE('{"AttributeName": "Value"}');


SELECT s.AttributeName FROM t1;  

attributename
-------------
NULL


SELECT s."AttributeName" FROM t1;

attributename
-------------
NULL
```

Amazon Redshift 會針對這兩個查詢傳回 NULL。若要查詢 `AttributeName`，請使用 LOWER\$1ATTRIBUTE\$1NAMES 將資料的屬性名稱轉換為小寫。請考量下列範例。

```
CREATE TABLE t2 (s) AS SELECT LOWER_ATTRIBUTE_NAMES(s) FROM t1;


SELECT s.attributename FROM t2;

attributename
-------------
"Value"


SELECT s.AttributeName FROM t2; 

attributename
-------------
"Value"


SELECT s."attributename" FROM t2;

attributename
-------------
"Value"


SELECT s."AttributeName" FROM t2;

attributename
-------------
"Value"
```

使用混合大小寫物件屬性名稱的相關選項為 `enable_case_sensitive_super_attribute` 組態選項，其可讓 Amazon Redshift 辨識 SUPER 屬性名稱中的大小寫。這可作為使用 LOWER\$1ATTRIBUTE\$1NAMES 的替代解決方案。如需 `enable_case_sensitive_super_attribute` 的詳細資訊，請前往 [enable\$1case\$1sensitive\$1super\$1attribute](r_enable_case_sensitive_super_attribute.md)。

## 範例
<a name="r_lower_attribute_names_examples"></a>

**將 SUPER 屬性名稱轉換為小寫**  
下列範例使用 LOWER\$1ATTRIBUTE\$1NAMES 來轉換資料表中所有 SUPER 值的屬性名稱。

```
-- Create a table and insert several SUPER values.
CREATE TABLE t (i INT, s SUPER);

INSERT INTO t VALUES
  (1, NULL), 
  (2, 'A'::SUPER),
  (3, JSON_PARSE('{"AttributeName": "B"}')),
  (4, JSON_PARSE(
     '[{"Subobject": {"C": "C"},
        "Subarray": [{"D": "D"}, "E"]
      }]'));

-- Convert all attribute names to lowercase.
UPDATE t SET s = LOWER_ATTRIBUTE_NAMES(s);

SELECT i, s FROM t ORDER BY i;

 i |                        s
---+--------------------------------------------------
 1 | NULL
 2 | "A"
 3 | {"attributename":"B"}
 4 | [{"subobject":{"c":"C"},"subarray":[{"d":"D"}, "E"]}]
```

請注意 LOWER\$1ATTRIBUTE\$1NAMES 的運作方式。
+  NULL 值和純量 SUPER 值 (例如 `"A"`) 會保持不變。
+  在 SUPER 物件中，所有屬性名稱都會變更為小寫，但屬性值 (例如 `"B"`) 則保持不變。
+  LOWER\$1ATTRIBUTE\$1NAMES 會反覆套用至 SUPER 陣列內或其他物件內的任何巢狀 SUPER 物件。

**對擁有重複屬性名稱的 SUPER 物件使用 LOWER\$1ATTRIBUTE\$1NAMES**  
如果 SUPER 物件包含的屬性名稱只有大小寫不同，LOWER\$1ATTRIBUTE\$1NAMES 將會引發錯誤。請考量下列範例。

```
SELECT LOWER_ATTRIBUTE_NAMES(JSON_PARSE('{"A": "A", "a": "a"}'));      

error:   Invalid input
code:    8001
context: SUPER value has duplicate attributes after case conversion.
```

# OBJECT 函數
<a name="r_object_function"></a>

建立 SUPER 資料類型的物件。

## 語法
<a name="r_object_function-synopsis"></a>

```
OBJECT ( [ key1, value1 ], [ key2, value2 ...] )
```

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

*key1, key2*  
計算結果為 VARCHAR 類型字串的運算式。

*value1, value2*  
除了日期時間類型以外的任何 Amazon Redshift 資料類型的運算式，因為 Amazon Redshift 不會將日期時間類型轉換為 SUPER 資料類型。如需日期時間類型的相關資訊，請參閱[日期時間 (Datetime) 類型](r_Datetime_types.md)。  
物件中的 `value` 運算式不需要是相同的資料類型。

## 傳回類型
<a name="r_object_function-returns"></a>

`SUPER`

## 範例
<a name="r_object_function_example"></a>

```
-- Creates an empty object.
select object();

object
--------
{}
(1 row)
            
-- Creates objects with different keys and values.
select object('a', 1, 'b', true, 'c', 3.14);

object
---------------------------
{"a":1,"b":true,"c":3.14}
(1 row)
               
select object('a', object('aa', 1), 'b', array(2,3), 'c', json_parse('{}'));
               
object
---------------------------------
{"a":{"aa":1},"b":[2,3],"c":{}}
(1 row)
            
-- Creates objects using columns from a table.
create table bar (k varchar, v super);
insert into bar values ('k1', json_parse('[1]')), ('k2', json_parse('{}'));
select object(k, v) from bar;

object
------------
{"k1":[1]}
{"k2":{}}
(2 rows)
            
-- Errors out because DATE type values can't be converted to SUPER type.
select object('k', '2008-12-31'::date);

ERROR:  OBJECT could not convert type date to super
```

# OBJECT\$1TRANSFORM 函數
<a name="r_object_transform_function"></a>

變換 SUPER 物件。

## 語法
<a name="r_object_transform_function-synopsis"></a>

```
OBJECT_TRANSFORM(
  input
  [KEEP path1, ...]
  [SET
    path1, value1,
    ...,  ...
  ]
)
```

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

*input*  
解析為 SUPER 類型物件的表達式。

*KEEP*  
在這個子句中指定的所有*路徑*值都會保留，並轉移到輸出物件。  
此子句是選用的。

*path1*、*path2*...  
常數字串常值，採用以句點分隔的雙引號路徑元件的格式。例如，`'"a"."b"."c"'` 是有效的路徑值。這適用於 KEEP 和 SET 子句中的路徑參數。

*SET*  
*path* 和 *value* 配對可修改現有路徑或新增路徑，並在輸出物件中設定該路徑的值。  
此子句是選用的。

*value1*、*value2*...  
解析為 SUPER 類型值的表達式。請注意，數字、文字和布林值類型可以解析為 SUPER。

## 傳回類型
<a name="r_object_transform_function-returns"></a>

`SUPER`

## 使用須知
<a name="r_object_transform_function-usage-notes"></a>

OBJECT\$1TRANSFORM 會傳回 SUPER 類型物件，其中包含來自 KEEP 中指定的 *input*路徑值，以及 SET 中指定的 *path* 和 *value* 對。

如果 KEEP 和 SET 都是空的，OBJECT\$1TRANSFORM 會傳回 *input*。

如果 *input* 不是 SUPER 類型 *object*，則 OBJECT\$1TRANSFORM 會傳回 *input*，而不管任何 KEEP 或 SET 值。

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

下列範例會將 SUPER 物件轉換成另一個 SUPER 物件。

```
CREATE TABLE employees (
    col_person SUPER
);

INSERT INTO employees
VALUES
    (
        json_parse('
            {
                "name": {
                    "first": "John",
                    "last": "Doe"
                },
                "age": 25,
                "ssn": "111-22-3333",
                "company": "Company Inc.",
                "country": "U.S."
            }
        ')
    ),
    (
        json_parse('
            {
                "name": {
                    "first": "Jane",
                    "last": "Appleseed"
                },
                "age": 34,
                "ssn": "444-55-7777",
                "company": "Organization Org.",
                "country": "Ukraine"
            }
        ')
    )
;

SELECT
    OBJECT_TRANSFORM(
        col_person
        KEEP
            '"name"."first"',
            '"age"',
            '"company"',
            '"country"'
        SET
            '"name"."first"', UPPER(col_person.name.first::TEXT),
            '"age"', col_person.age + 5,
            '"company"', 'Amazon'
    ) AS col_person_transformed
FROM employees;
    
--This result is formatted for ease of reading.
                  col_person_transformed
-------------------------------------------------------------
{
    "name": {
        "first": "JOHN"
    },
    "age": 30,
    "company": "Amazon",
    "country": "U.S."
}
{
    "name": {
        "first": "JANE"
    },
    "age": 39,
    "company": "Amazon",
    "country": "Ukraine"
}
```

# UPPER\$1ATTRIBUTE\$1NAMES 函式
<a name="r_upper_attribute_names"></a>

使用與 [UPPER 函數](r_UPPER.md) 相同的大小寫轉換常式，將 SUPER 值中所有適用的屬性名稱轉換為大寫。UPPER\$1ATTRIBUTE\$1NAMES 支援 UTF-8 多位元組字元，每個字元最多 4 個位元組。

 若要將 SUPER 屬性名稱轉換為小寫，請使用 [LOWER\$1ATTRIBUTE\$1NAMES 函式](r_lower_attribute_names.md)。

## 語法
<a name="r_upper_attribute_names-synopsis"></a>

```
UPPER_ATTRIBUTE_NAMES( super_expression )
```

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

*super\$1expression*  
SUPER 表達式。

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

`SUPER`

## 範例
<a name="r_upper_attribute_names_examples"></a>

**將 SUPER 屬性名稱轉換為大寫**  
下列範例使用 UPPER\$1ATTRIBUTE\$1NAMES 來轉換資料表中所有 SUPER 值的屬性名稱。

```
-- Create a table and insert several SUPER values.
CREATE TABLE t (i INT, s SUPER);

INSERT INTO t VALUES
  (1, NULL), 
  (2, 'a'::SUPER),
  (3, JSON_PARSE('{"AttributeName": "b"}')),
  (4, JSON_PARSE(
     '[{"Subobject": {"c": "c"},
        "Subarray": [{"d": "d"}, "e"]
      }]'));

-- Convert all attribute names to uppercase.
UPDATE t SET s = UPPER_ATTRIBUTE_NAMES(s);

SELECT i, s FROM t ORDER BY i;

 i |                        s
---+--------------------------------------------------
 1 | NULL
 2 | "a"
 3 | {"ATTRIBUTENAME":"B"}
 4 | [{"SUBOBJECT":{"C":"c"},"SUBARRAY":[{"D":"d"}, "e"]}]
```

請注意 UPPER\$1ATTRIBUTE\$1NAMES 的運作方式。
+  NULL 值和純量 SUPER 值 (例如 `"a"`) 會保持不變。
+  在 SUPER 物件中，所有屬性名稱都會變更為大寫，但屬性值 (例如 `"b"`) 則保持不變。
+  UPPER\$1ATTRIBUTE\$1NAMES 會反覆套用至 SUPER 陣列內或其他物件內的任何巢狀 SUPER 物件。

**對擁有重複屬性名稱的 SUPER 物件使用 UPPER\$1ATTRIBUTE\$1NAMES**  
如果 SUPER 物件包含的屬性名稱只有大小寫不同，UPPER\$1ATTRIBUTE\$1NAMES 將會引發錯誤。請考量下列範例。

```
SELECT UPPER_ATTRIBUTE_NAMES(JSON_PARSE('{"A": "A", "a": "a"}'));      

error:   Invalid input
code:    8001
context: SUPER value has duplicate attributes after case conversion.
```