本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon Keys UDTs paces 中的用户定义类型 ()
用户定义类型 (UDT) 是一组字段和数据类型，可用于在 Amazon Keyspaces 中定义单个列。的有效数据类型 UDTs 是所有支持的 Cassandra 数据类型，包括集合和你 UDTs 已经在同一个密钥空间中创建的其他数据类型。有关支持的 Cassandra 数据类型的更多信息，请参阅[Cassandra 数据类型支持](cassandra-apis.md#cassandra-data-type)。
您可以在 Amazon Keyspaces 中使用用户定义的类型 (UDTs) 以更有效的方式组织数据。例如，您可以使用嵌套集合 UDTs 进行创建，从而可以在应用程序中实现更复杂的数据建模。您也可以使用 frozen 关键字进行定义 UDTs。
UDTs 绑定到密钥空间，可供所有表和 UDTs 同一个密钥空间使用。您可以在单区域和多区域密钥空间 UDTs 中创建。
您可以创建新表或更改现有表，也可以添加使用 UDT 的新列。要创建带有嵌套 UDT 的 UDT，必须冻结嵌套的 UDT。
要查看每个密钥空间支持 UDTs 多少密钥空间、支持的嵌套级别以及与之相关的其他默认值和配额 UDTs，请参阅。[Amazon Keyspaces 中用户定义类型 (UDTs) 的配额和默认值](quotas.md#quotas-udts)
有关如何计算的编码大小的信息 UDTs，请参见[根据数据类型估计数据值的编码大小](calculating-row-size.md#calculating-row-size-data-types)。
有关 CQL 语法的更多信息，请参阅 [用户定义的类型 (UDTs)](cql.ddl.type.md)。
要了解有关时间点恢复 UDTs 的更多信息，请参阅[PITR 还原用户定义类型的表 () UDTs](PointInTimeRecovery_HowItWorks.md#howitworks_backup_udt)。
**Topics**
+ [配置 权限](configure-udt-permissions.md)
+ [创建 UDT](keyspaces-create-udt.md)
+ [查看 UDTs](keyspaces-view-udt.md)
+ [删除 UDT](keyspaces-delete-udt.md)
# 在 Amazon Keyspaces 中配置使用用户定义类型 (UDTs) 的权限
与表一样， UDTs 也绑定到特定的密钥空间。但是与表不同，您不能直接为定义权限 UDTs。 UDTs 不被视为中的资源 AWS ，也没有亚马逊资源名称 (ARN) 格式的唯一标识符。相反，要向 IAM 委托人授予对 UDT 执行特定操作的权限，您必须为 UDT 绑定到的密钥空间定义权限。要 UDTs 在多区域密钥空间中使用，需要额外的权限。
为了能够创建、查看或删除 UDTs，委托人（例如 IAM 用户或角色）需要的权限与在 UDT 绑定到的密钥空间上执行相同操作所需的权限相同。
有关的更多信息 AWS Identity and Access Management，请参阅[AWS Identity and Access Management 适用于 Amazon Keyspaces](security-iam.md)。
## 创建 UDT 的权限
要在单区域密钥空间中创建 UDT，委托人需要密钥空间的`Create`权限。
以下 IAM 策略就是一个例子。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "cassandra:Create",
"Resource": [
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
]
}
]
}
```
要在多区域密钥空间中创建 UDT，除了`Create`权限外，委托人还需要对指定密钥空间执行操作`CreateMultiRegionResource`的权限。
以下 IAM 策略就是一个例子。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "cassandra:Create", "cassandra:CreateMultiRegionResource" ],
"Resource": [
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
]
}
]
}
```
## 查看 UDT 的权限
要在单区域密钥空间 UDTs 中查看或列出，主体需要系统密钥空间的读取权限。有关更多信息，请参阅 [`system_schema_mcs`](working-with-keyspaces.md#keyspace_system_schema_mcs)。
以下 IAM 策略就是一个例子。
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"cassandra:Select",
"Resource":[
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/system*"
]
}
]
}
```
要查看或列 UDTs 出多区域密钥空间，委托人需要操作权限`SELECT`和`SelectMultiRegionResource`系统密钥空间权限。有关更多信息，请参阅 [`system_multiregion_info`](working-with-keyspaces.md#keyspace_system_multiregion_info)。
以下 IAM 策略就是一个例子。
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action": ["cassandra:Select", "cassandra:SelectMultiRegionResource"],
"Resource":[
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/system*"
]
}
]
}
```
## 删除 UDT 的权限
要从单区域密钥空间中删除 UDT，委托人需要对指定密钥空间`Drop`执行操作的权限。
以下 IAM 策略就是一个例子。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "cassandra:Drop",
"Resource": [
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
]
}
]
}
```
要从多区域密钥空间中删除 UDT，委托人需要`Drop`操作权限和指定密钥空间的`DropMultiRegionResource`操作权限。
以下 IAM 策略就是一个例子。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "cassandra:Drop", "cassandra:DropMultiRegionResource" ],
"Resource": [
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
]
}
]
}
```
# 在 Amazon Keyspaces 中创建用户定义类型 (UDT)
要在单区域密钥空间中创建 UDT，可以使用 CQL 中的`CREATE TYPE`语句、带的`create-type` AWS CLI命令或控制台。
UDT 名称必须包含不超过 48 个字符，必须以字母字符开头，并且只能包含字母数字字符和下划线。Amazon Keyspaces 会自动将大写字符转换为小写字符。
或者，可以在双引号中声明 UDT 名称。在双引号内声明 UDT 名称时，Amazon Keyspaces 保留大写字母并支持使用特殊字符。
创建 UDT 时，也可以使用双引号作为名称的一部分，但必须使用额外的双引号字符对每个双引号字符进行转义。
下表显示了支持的 UDT 名称的示例。第一列显示在创建类型时如何输入名称，第二列显示 Amazon Keyspaces 如何在内部设置名称格式。Amazon Keyspaces 希望对操作使用诸如 `GetType` 之类的格式化名称。
| 输入的名字 | 格式化名称 | 注意 |
| --- | --- | --- |
| MY\$1UDT | my\$1udt | 如果不使用双引号，Amazon Keyspaces 会将所有大写字符转换为小写字母。 |
| "MY\$1UDT" | MY\$1UDT | 使用双引号时，Amazon Keyspace 采用大写字符，并从格式化名称中移除双引号。 |
| "1234" | 1234 | 使用双引号时，名称能够以数字开头，Amazon Keyspaces 会移除格式化名称中的双引号。 |
| "Special\$1Ch@r@cters<>\$1\$1" | Special\$1Ch@r@cters<>\$1\$1 | 使用双引号时，名称可以包含特殊字符，Amazon Keyspaces 会移除格式化名称中的双引号。 |
| "nested""""""quotes" | nested"""quotes | Amazon Keyspaces 从格式化名称中移除外部双引号和转义双引号。 |
------
#### [ Console ]
**使用 Amazon Keyspaces 控制台创建用户定义类型 (UDT)**
1. [登录并在家中打开 Amazon Keyspaces 控制台。 AWS 管理控制台 https://console.aws.amazon.com/keyspaces/](https://console.aws.amazon.com/keyspaces/home)
1. 在导航窗格中，选择 **Keyspaces**，然后从列表中选择一个密钥空间。
1. 选择 **UDTs** 选项卡。
1. 选择 “**创建 UDT**”
1. 在 **UDT 详细信息**下，输入 UDT 的名称。在 **UDT 字段**下，您可以定义 UDT 的架构。
1. 要完成操作，请选择 “**创建 UDT**”。
------
#### [ Cassandra Query Language (CQL) ]
**使用 CQL 创建用户定义类型 (UDT)**
在此示例中，我们创建了中使用的图书奖励表的新版本[在 Amazon Keyspaces 中创建表](getting-started.tables.md)。在此表中，我们存储了作者因某本书而获得的所有奖项。我们创建了两个嵌套 UDTs 的书籍，其中包含有关获得奖项的图书的信息。
1. 使用名称`catalog`创建密钥空间。
```
CREATE KEYSPACE catalog WITH REPLICATION = {'class': 'SingleRegionStrategy'};
```
1. 创建第一个类型。这种类型存储 *BISAC* 代码，这些代码用于定义书籍的类型。BISAC 代码由字母数字代码和最多四个主题区域组成。
```
CREATE TYPE catalog.bisac (
bisac_code text,
subject1 text,
subject2 text,
subject3 text,
subject4 text
);
```
1. 使用第一个 UDT 为图书奖励创建第二种类型。必须冻结嵌套的 UDT。
```
CREATE TYPE catalog.book (
award_title text,
book_title text,
publication_date date,
page_count int,
ISBN text,
genre FROZEN
);
```
1. 创建一个包含作者姓名列的表格，并使用列表类型作为图书奖项。请注意，必须冻结列表中使用的 UDT。
```
CREATE TABLE catalog.authors (
author_name text PRIMARY KEY,
awards list >
);
```
1. 在此步骤中，我们在新表中插入一行数据。
```
CONSISTENCY LOCAL_QUORUM;
```
```
INSERT INTO catalog.authors (author_name, awards) VALUES (
'John Stiles' ,
[{
award_title: 'Wolf',
book_title: 'Yesterday',
publication_date: '2020-10-10',
page_count: 345,
ISBN: '026204630X',
genre: { bisac_code:'FIC014090', subject1: 'FICTION', subject2: 'Historical', subject3: '20th Century', subject4: 'Post-World War II'}
},
{award_title: 'Richard Roe',
book_title: 'Who ate the cake?',
publication_date: '2019-05-13',
page_count: 193,
ISBN: '9780262046305',
genre: { bisac_code:'FIC022130', subject1: 'FICTION', subject2: 'Mystery & Detective', subject3: 'Cozy', subject4: 'Culinary'}
}]
);
```
1. 在最后一步中，我们从表中读取数据。
```
SELECT * FROM catalog.authors;
```
命令的输出应如下所示。
```
author_name | awards
-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
John Stiles | [{award_title: 'Wolf', book_title: 'Yesterday', publication_date: 2020-10-10, page_count: 345, isbn: '026204630X', genre: {bisac_code: 'FIC014090', subject1: 'FICTION', subject2: 'Historical', subject3: '20th Century', subject4: 'Post-World War II'}}, {award_title: 'Richard Roe', book_title: 'Who ate the cake?', publication_date: 2019-05-13, page_count: 193, isbn: '9780262046305', genre: {bisac_code: 'FIC022130', subject1: 'FICTION', subject2: 'Mystery & Detective', subject3: 'Cozy', subject4: 'Culinary'}}]
(1 rows)
```
有关 CQL 语法的更多信息，请参阅 [CREATE TYPE](cql.ddl.type.md#cql.ddl.type.create)。
------
#### [ CLI ]
**使用创建用户定义类型 (UDT) AWS CLI**
1. 要创建类型，可以使用以下语法。
```
aws keyspaces create-type
--keyspace-name 'my_keyspace'
--type-name 'my_udt'
--field-definitions
'[
{"name" : "field1", "type" : "int"},
{"name" : "field2", "type" : "text"}
]'
```
1. 该命令的输出与本示例类似。请注意，`typeName`返回 UDT 的格式化名称。
```
{
"keyspaceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/",
"typeName": "my_udt"
}
```
------
# 在 Amazon Keyspac UDTs es 中查看用户定义的类型 ()
要查看或列出单区域密钥空间 UDTs 中的所有内容，可以使用 CQL `system_schema_mcs.types` 中的语句查询系统密钥空间中的表，或者在、或控制台中使用`get-type`和`list-type`命令。 AWS CLI
对于任一选项，IAM 委托人都需要对系统密钥空间的读取权限。有关更多信息，请参阅 [在 Amazon Keyspaces 中配置使用用户定义类型 (UDTs) 的权限](configure-udt-permissions.md)。
------
#### [ Console ]
**使用 Amazon Keyspaces 控制台查看用户定义的类型 (UDT)**
1. [登录并在家中打开 Amazon Keyspaces 控制台。 AWS 管理控制台 https://console.aws.amazon.com/keyspaces/](https://console.aws.amazon.com/keyspaces/home)
1. 在导航窗格中，选择 **Keyspaces**，然后从列表中选择一个密钥空间。
1. 选择该**UDTs**选项卡可查看密钥空间 UDTs 中所有内容的列表。
1. 要详细查看一个 UDT，请从列表中选择一个 **UDT**。
1. 在 “**架构**” 选项卡上，您可以查看架构。在 “**使用于**” 选项卡上，您可以查看此 UDT 是否用于表或其他 UDTs表中。请注意，您只能删除 UDTs 未被表或其他表使用的内容 UDTs。
------
#### [ Cassandra Query Language (CQL) ]
**使用 CQL 查看单区域密钥空间的用户定义类型 (UDTs)**
1. 要查看给定密钥空间中可用的类型，可以使用以下语句。
```
SELECT type_name
FROM system_schema_mcs.types
WHERE keyspace_name = 'my_keyspace';
```
1. 要查看有关特定类型的详细信息，可以使用以下语句。
```
SELECT
keyspace_name,
type_name,
field_names,
field_types,
max_nesting_depth,
last_modified_timestamp,
status,
direct_referring_tables,
direct_parent_types
FROM system_schema_mcs.types
WHERE keyspace_name = 'my_keyspace' AND type_name = 'my_udt';
```
1. 您可以使用列出账户中 UDTs 存在的所有内容`DESC TYPE`。
```
DESC TYPES;
Keyspace my_keyspace
---------------------------
my_udt1 my_udt2
Keyspace my_keyspace2
---------------------------
my_udt1
```
1. 您可以使用列出当前选定密钥`DESC TYPE`空间 UDTs 中的所有内容。
```
USE my_keyspace;
my_keyspace DESC TYPES;
my_udt1 my_udt2
```
1. 要列出多区域密钥空间 UDTs 中的所有内容，可以在密钥空间`types`中查询系统表。`system_multiregion_info`以下查询就是一个例子。
```
SELECT keyspace_name, type_name, region, status FROM system_multiregion_info.types WHERE keyspace_name = 'mykeyspace' AND table_name = 'mytable';
```
此命令的输出如下所示。
```
keyspace_name | table_name | region | status
mykeyspace | mytable | us-east-1 | ACTIVE
mykeyspace | mytable | ap-southeast-1 | ACTIVE
mykeyspace | mytable | eu-west-1 | ACTIVE
```
------
#### [ CLI ]
**使用查看用户定义的类型 (UDTs) AWS CLI**
1. 要列出密钥空间中可用的类型，可以使用`list-types`命令。
```
aws keyspaces list-types
--keyspace-name 'my_keyspace'
```
该命令的输出与本示例类似。
```
{
"types": [
"my_udt",
"parent_udt"
]
}
```
1. 要查看有关给定类型的详细信息，可以使用`get-type`命令。
```
aws keyspaces get-type
--type-name 'my_udt'
--keyspace-name 'my_keyspace'
```
此命令的输出类似于此示例。
```
{
"keyspaceName": "my_keyspace",
"typeName": "my_udt",
"fieldDefinitions": [
{
"name": "a",
"type": "int"
},
{
"name": "b",
"type": "text"
}
],
"lastModifiedTimestamp": 1721328225776,
"maxNestingDepth": 3
"status": "ACTIVE",
"directReferringTables": [],
"directParentTypes": [
"parent_udt"
],
"keyspaceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
}
```
------
# 删除 Amazon Keyspaces 中的用户定义类型 (UDT)
要删除密钥空间中的 UDT，可以使用 CQL 中的`DROP TYPE`语句、带的`delete-type`命令或控制 AWS CLI台。
------
#### [ Console ]
**使用 Amazon Keyspaces 控制台删除用户定义的类型 (UDT)**
1. [登录并在家中打开 Amazon Keyspaces 控制台。 AWS 管理控制台 https://console.aws.amazon.com/keyspaces/](https://console.aws.amazon.com/keyspaces/home)
1. 在导航窗格中，选择 **Keyspaces**，然后从列表中选择一个密钥空间。
1. 选择 **UDTs** 选项卡。
1. 选择要删除的 UDT。**在 “Used in” 上，您可以确认要删除的类型当前未被表或其他 UDT 使用。**
1. 选择 “**摘要****” 上方的 “删除**”。
1. `Delete`在出现的对话框中键入，然后选择 “**删除 UDT**”。
------
#### [ Cassandra Query Language (CQL) ]
**使用 CQL 删除用户定义类型 (UDT)**
+ 要删除类型，可以使用以下语句。
```
DROP TYPE my_keyspace.my_udt;
```
有关 CQL 语法的更多信息，请参阅 [DROP TYPE](cql.ddl.type.md#cql.ddl.type.drop)。
------
#### [ CLI ]
**使用删除用户定义的类型 (UDT) AWS CLI**
1. 要删除类型，可以使用以下命令。
```
aws keyspaces delete-type
--keyspace-name 'my_keyspace'
--type-name 'my_udt'
```
1. 该命令的输出类似于此示例。
```
{
"keyspaceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/",
"typeName": "my_udt"
}
```
------