文档首页/ 湖仓构建 LakeFormation/ API参考/ API/ LakeCat类API/ 元数据管理/ 搜索元数据 - SearchMetadata
更新时间：2026-08-11 GMT+08:00
查看PDF
分享

搜索元数据 - SearchMetadata

功能介绍

搜索元数据

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

POST /v1/{project_id}/instances/{instance_id}/metadata/search

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释:

项目编号。获取方法，请参见获取项目ID。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

instance_id

是

String

参数解释:

LakeFormation实例ID。创建实例时自动生成。例如：2180518f-42b8-4947-b20b-adfc53981a25。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

Array of strings

参数解释:

租户token。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及
表3 请求Body参数

参数

是否必选

参数类型

描述

name_pattern

是

String

参数解释:

元数据名称通配符。

约束限制:

只能包含中文、字母、数字和_-|*.特殊字符，且长度为1到256个字符。

取值范围:

不涉及

默认取值:

不涉及

metadata_type

是

String

参数解释:

元数据资源类型：CATALOG、DATABASE、TABLE、FUNC、DATASET

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

limit

否

Integer

参数解释:

查询返回条数。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

marker

否

String

参数解释:

查询的起始记录ID。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

reverse_page

否

Boolean

参数解释:

是否倒序查询。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

响应参数

状态码：200

表4 响应Body参数

参数

参数类型

描述

page_info

PagedInfo object

分页信息。

catalogs

Array of Catalog objects

元数据列表

databases

Array of Database objects

元数据列表

tables

Array of Table objects

元数据列表

functions

Array of Function objects

元数据列表

datasets

Array of Dataset objects

元数据列表
表5 PagedInfo

参数

参数类型

描述

current_count

Integer

参数解释:

本次返回的对象个数。最小值为0，最大值为2000

next_marker

String

参数解释:

下一页查询地址。当不存在下一页，则值为null，当值为null时，响应Body无该参数

previous_marker

String

参数解释:

上一页查询地址。当不存在上一页，则值为null，当值为null时，响应Body无该参数
表6 Catalog

参数

参数类型

描述

catalog_name

String

参数解释:

catalog名称

catalog_id

String

参数解释:

catalogID

description

String

参数解释:

描述信息

location

String

参数解释:

路径地址。例如obs://location/uri/

database_location_list

Array of strings

参数解释:

数据库路径列表。当值为null时，响应Body无该参数

owner

String

参数解释:

catalog所有者。LakeFormation服务分为一期和二期，一期响应Body无该参数

owner_type

String

参数解释:

所有者类型，USER-用户，GROUP-组，ROLE-角色。LakeFormation服务分为一期和二期，一期响应Body无该参数

owner_source

String

参数解释:

所有者来源：IAM-云用户、SAML-联邦、LDAP-ld用户、LOCAL-本地用户、AGENTTENANT-委托、OTHER-其它。LakeFormation服务分为一期和二期，一期响应Body无该参数

type

String

参数解释:

catalog类型，可选值为DEFAULT（代表默认的元数据类型）、CLICKHOUSE（代表CH类型），不设置时默认为DEFAULT。

创建时指定，不可修改

create_time

String

参数解释:

catalog元数据创建时间

update_time

String

参数解释:

catalog元数据最后一次修改时间

version_id

String

参数解释:

版本ID
表7 Database

参数

参数类型

描述

catalog_name

String

参数解释:

catalog名称

catalog_id

String

参数解释:

catalogID

database_name

String

参数解释:

数据库名称

database_id

String

参数解释:

数据库ID

database_status

Integer

参数解释:

数据库状态：0表示正常，1表示删除中，2表示已删除，3表示恢复中，4表示清除中

external_database_id

String

参数解释:

用户端数据库id，创建时指定，不可修改

owner

String

参数解释:

数据库所有者

owner_type

String

参数解释:

所有者类型：USER-用户、GROUP-组、ROLE-角色

owner_auth_source_type

String

参数解释:

所有者授权来源类型：IAM-云用户、SAML-联邦、LDAP-ld用户、LOCAL-本地用户、AGENTTENANT-委托、OTHER-其它。LakeFormation服务分为一期和二期，一期响应Body无该参数

description

String

参数解释:

数据库描述信息

location

String

参数解释:

数据库路径地址。例如obs://location/uri/

data_statistic_enable

Boolean

参数解释:

数据概况统计开关。默认状态为关，若要开启database下table的数据概况统计，需要先打开database的数据概况开关。database此开关开启后，database下所有table都会默认开启此开关

parameters

Map<String,String>

参数解释:

参数信息

table_location_list

Array of strings

参数解释:

表路径列表。LakeFormation服务分为一期和二期，一期响应Body无该参数，二期默认为null。当值为null时，响应Body无该参数

function_location_list

Array of strings

参数解释:

函数路径列表。默认为null，当值为null时，响应Body无该参数

update_time

String

参数解释:

数据库元数据最后一次修改时间

version_id

String

参数解释:

版本ID

connection_name

String

参数解释:

连接名称

database_type

String

参数解释:

数据库类型：MANAGED_DATABASE内置数据库、FOREIGN_DATABASE外置数据库
表8 Table

参数

参数类型

描述

catalog_name

String

参数解释:

catalog名称

catalog_id

String

参数解释:

catalogID

database_name

String

参数解释:

数据库名称

database_id

String

参数解释:

数据库ID

table_name

String

参数解释:

表名称

table_id

String

参数解释:

表ID

table_status

Integer

参数解释:

表状态，0表示正常，1表示删除中，2表示已删除，3表示恢复中，4表示清除中

external_table_id

String

参数解释:

用户端表id，创建时指定，不可修改

create_time

String

参数解释:

表创建时间

last_access_time

String

参数解释:

最后访问时间

update_time

String

参数解释:

表元数据最后一次修改时间

last_analyzed_time

String

参数解释:

上一次做列级别的统计信息计算的时间

owner

String

参数解释:

用户信息

owner_type

String

参数解释:

用户类型，USER-用户，GROUP-组，ROLE-角色

parameters

Map<String,String>

参数解释:

参数

partition_keys

Array of Column objects

参数解释:

表分区列的列表

retention

Integer

参数解释:

表保留时间

storage_descriptor

StorageDescriptor object

参数解释:

数据存储

table_format

String

参数解释:

表格式。支持{HIVE,ICEBERG,LANCE}，默认值为HIVE

table_type

String

参数解释:

表类型，MANAGED_TABLE-内表，EXTERNAL_TABLE-外表，VIRTUAL_VIEW-视图，MATERIALIZED_VIEW-物化视图，DICTIONARY_TABLE字典表，LAKE_TABLE内表，LAKE_MATERIALIZED_VIEW-内部物化视图

comments

String

参数解释:

表描述信息

view_expanded_text

String

参数解释:

如果表是视图，则为视图的扩展文本

view_original_text

String

参数解释:

如果表是视图，则为视图的原始文本

data_statistic_enable

Boolean

参数解释:

数据概况统计开关。默认状态为开，修改table开关状态后，还需检查所属database的开关状态。例如：table与所属database开关同时打开，则数据概况统计开启。否则关闭

version_id

String

参数解释:

版本ID
表9 StorageDescriptor

参数

参数类型

描述

columns

Array of Column objects

参数解释:

分区列以外的所有字段

取值范围:

数组元素个数为0~10000

location

String

参数解释:

路径地址。例如obs://location/uri/

取值范围:

最大长度为4000

compressed

Boolean

参数解释:

是否启用数据压缩。默认为false

取值范围:

不涉及

input_format

String

参数解释:

输入格式

取值范围:

长度为0~128个字符

output_format

String

参数解释:

输出格式

取值范围:

长度为0~128个字符

number_of_buckets

Integer

参数解释:

分桶的桶数量。默认值为0

取值范围:

取值为-1~2147483647

bucket_columns

Array of strings

参数解释:

分桶字段

取值范围:

长度为1~255个字符，数组元素个数为0~200

sort_columns

Array of Order objects

参数解释:

指定表中的每个存储桶的排序顺序的列表

取值范围:

数组元素个数为0~10000

serde_info

SerDeInfo object

参数解释:

序列化/反序列化信息

取值范围:

不涉及

parameters

Map<String,String>

参数解释:

存储描述符的参数，键和值为字符串，长度不超过100000

取值范围:

长度为0~100000个字符

skewed_info

SkewedInfo object

参数解释:

有关在列中经常出现的值（偏斜值）的信息

取值范围:

不涉及

stored_as_sub_directories

Boolean

参数解释:

数据是否会存放在子目录中

取值范围:

不涉及
表10 Column

参数

参数类型

描述

column_type

String

参数解释:

说明：

取值范围:

长度为1~65535个字符

column_name

String

参数解释:

列名称。只能包含中文、字母、数字和_-+*(), 特殊字符，且长度为1~767个字符

取值范围:

长度为1~767个字符

comment

String

参数解释:

列描述信息。最大长度为4000个字符

取值范围:

长度为0~4000个字符

advance_column_type

String

参数解释:

用户自定义类型名称，当且仅当column_type为struct，字段可填写。该字段存在值时，表示用户自定义的高阶类型

取值范围:

长度为0~64个字符
表11 Order

参数

参数类型

描述

column

String

参数解释:

列名称。只能包含中文、字母、数字和_-+*(), 特殊字符，且长度为1~767个字符

取值范围:

长度为1~767个字符

sort_order

Integer

参数解释:

指示是按升序 (== 1) 还是降序 (==0) 对列进行排序

取值范围:

取值为0~1
表12 SerDeInfo

参数

参数类型

描述

name

String

参数解释:

名称信息

取值范围:

长度为0~256个字符

serialization_library

String

参数解释:

实现序列化/反序列化的类

取值范围:

长度为0~256个字符

parameters

Map<String,String>

参数解释:

参数数组，键和值为字符串，长度不超过100000

取值范围:

长度为0~100000个字符
表13 SkewedInfo

参数

参数类型

描述

skewed_column_names

Array of strings

参数解释:

数据偏移列的列表

取值范围:

长度为1~256个字符，数组元素个数为0~100000

skewed_column_value_location_maps

Map<String,String>

参数解释:

偏斜值和地址的映射关系

取值范围:

长度为0~65534个字符

skewed_column_values

Array<Array<String>>

参数解释:

偏斜值的列表

取值范围:

长度为0~65534个字符，数组元素个数为0~100000
表14 Function

参数

参数类型

描述

catalog_name

String

参数解释:

catalog名称

catalog_id

String

参数解释:

catalogID

database_name

String

参数解释:

数据库名称

database_id

String

参数解释:

数据库ID

function_name

String

参数解释:

函数名称。只能包含字母、数字和下划线，且长度为1~256个字符

function_type

String

参数解释:

函数类型,JAVA,remoteUDF,PYTHON,LAKE

function_id

String

参数解释:

函数ID

owner

String

参数解释:

函数所有者。只能包含字母、数字和下划线，且长度为1~256个字符

owner_type

String

参数解释:

所有者类型：USER-用户、GROUP-组、ROLE-角色

owner_auth_source_type

String

参数解释:

所有者授权来源类型：IAM-云用户、SAML-联邦、LDAP-ld用户、LOCAL-本地用户、AGENTTENANT-委托、OTHER-其它。LakeFormation服务分为一期和二期，一期响应Body无该参数

class_name

String

参数解释:

函数类名

create_time

String

参数解释:

函数创建时间

update_time

String

参数解释:

函数元数据最后一次修改时间

resource_uris

Array of FunctionResourceUri objects

参数解释:

函数地址信息

version_id

String

参数解释:

版本ID

parameters

Map<String,String>

参数解释:

参数
表15 FunctionResourceUri

参数

参数类型

描述

type

String

参数解释:

函数包类型：JAR，FILE，ARCHIVE，URI

取值范围:

不涉及

uri

String

参数解释:

函数包地址信息

取值范围:

长度为1~4096个字符
表16 Dataset

参数

参数类型

描述

catalog_name

String

参数解释:

catalog名称

catalog_id

String

参数解释:

catalogID

dataset_name

String

参数解释:

数据集名称

dataset_id

String

参数解释:

DatasetID

description

String

参数解释:

数据集的描述信息

database_name

String

数据库名称。

database_id

String

数据库ID。

storage_type

String

参数解释:

数据集存储类型：EXTERNAL-外置存储,MANAGED-系统托管存储

dataset_format

DatasetFileFormat object

文件类型

owner

String

参数解释:

Dataset所有者

owner_type

String

参数解释:

所有者类型,USER-用户,GROUP-组,ROLE-角色。LakeFormation服务一期实例响应Body无该参数

owner_source

String

参数解释:

所有者来源,IAM-云用户,SAML-联邦,LDAP-ld用户,LOCAL-本地用户,AGENTTENANT-委托,OTHER-其它。LakeFormation服务一期实例响应Body无该参数

location

String

参数解释:

外置存储类型的元数据存储位置

properties

Map<String,String>

参数解释:

数据集其他属性

create_time

String

参数解释:

数据集创建时间

update_time

String

参数解释:

数据集修改时间
表17 DatasetFileFormat

参数

参数类型

描述

format

String

参数解释:

文件格式：

ROW-行存储文件

TEXT-无格式文本文件

IMAGE-图片文件

AUDIO-音频文件

VIDEO-视频文件

CUSTOM-其他文件

取值范围:

不涉及

content_types

Array of strings

参数解释:

内容类型列表

取值范围:

长度为0~64个字符

状态码：400

表18 响应Body参数

参数

参数类型

描述

error_code

String

参数解释:

错误码

error_msg

String

参数解释:

错误描述

solution_msg

String

参数解释:

解决方案描述

状态码：401

表19 响应Body参数

参数

参数类型

描述

error_code

String

参数解释:

错误码

error_msg

String

参数解释:

错误描述

solution_msg

String

参数解释:

解决方案描述

状态码：403

表20 响应Body参数

参数

参数类型

描述

error

Error object

参数解释:

错误信息

error_code

String

参数解释:

错误码

error_msg

String

参数解释:

错误描述

title

String

参数解释:

标题
表21 Error

参数

参数类型

描述

error_code

String

参数解释:

错误码

error_msg

String

参数解释:

错误描述

title

String

参数解释:

标题

message

String

参数解释:

错误信息

code

String

参数解释:

状态码

状态码：404

表22 响应Body参数

参数

参数类型

描述

error_code

String

参数解释:

错误码

error_msg

String

参数解释:

错误描述

solution_msg

String

参数解释:

解决方案描述

状态码：408

表23 响应Body参数

参数

参数类型

描述

error_code

String

参数解释:

错误码

error_msg

String

参数解释:

错误描述

solution_msg

String

参数解释:

解决方案描述

状态码：500

表24 响应Body参数

参数

参数类型

描述

error_code

String

参数解释:

错误码

error_msg

String

参数解释:

错误描述

solution_msg

String

参数解释:

解决方案描述

请求示例

POST https://{endpoint}/v1/{project_id}/instances/{instance_id}/metadata/search

{
  "name_pattern" : "hive",
  "metadata_type" : "CATALOG"
}

响应示例

状态码：200

OK

{
  "page_info" : {
    "current_count" : 3,
    "next_marker" : "006f492b-xxxx",
    "previous_marker" : "003e6eba-xxxx"
  },
  "catalogs" : [ {
    "catalog_name" : "hive",
    "description" : "Default catalog, for Hive",
    "location" : "obs://lakeformation/test",
    "database_location_list" : null,
    "owner" : "admin",
    "owner_type" : "USER",
    "owner_source" : "IAM"
  } ],
  "databases" : [ {
    "catalog_name" : "hive",
    "database_name" : "default",
    "owner" : "lakeformation",
    "owner_type" : "USER",
    "owner_auth_source_type" : "IAM",
    "description" : "",
    "location" : "obs://lakeformation/test",
    "parameters" : {
      "transient_lastDdlTime" : "120",
      "comment" : "comment message",
      "classification" : "other"
    },
    "table_location_list" : [ ],
    "function_location_list" : [ ]
  } ],
  "tables" : [ {
    "catalog_name" : "hive",
    "database_name" : "default",
    "table_name" : "tbl",
    "create_time" : "2022-11-19T03:10:14.000+00:00",
    "last_access_time" : "2022-12-31T23:59:59.000+00:00",
    "update_time" : null,
    "last_analyzed_time" : null,
    "owner" : "lakeformation",
    "owner_type" : "USER",
    "parameters" : {
      "ww" : "ww",
      "transient_lastDdlTime" : "1668827414",
      "classification" : "avro",
      "www" : "ww",
      "wwww" : "ww"
    },
    "partition_keys" : [ ],
    "retention" : 0,
    "storage_descriptor" : {
      "columns" : [ {
        "column_type" : "tinyint",
        "column_name" : "ww",
        "comment" : null
      } ],
      "location" : "obs://lakeformation/test",
      "compressed" : true,
      "input_format" : "org.apache.hadoop.hive.ql.io.avro.AvroContainerInputFormat",
      "output_format" : "org.apache.hadoop.hive.ql.io.avro.AvroContainerOutputFormat",
      "number_of_buckets" : 0,
      "bucket_columns" : [ ],
      "sort_columns" : [ ],
      "serde_info" : {
        "name" : "name",
        "serialization_library" : "org.apache.hadoop.hive.serde2.avro.AvroSerDe",
        "parameters" : {
          "serialization.format" : "1"
        }
      },
      "parameters" : { },
      "skewed_info" : {
        "skewed_column_names" : [ ],
        "skewed_column_value_location_maps" : { },
        "skewed_column_values" : [ ]
      },
      "stored_as_sub_directories" : false
    },
    "table_format" : "HIVE",
    "table_type" : "MANAGED_TABLE",
    "comments" : "",
    "view_expanded_text" : "",
    "view_original_text" : ""
  } ],
  "functions" : [ {
    "function_name" : "func",
    "function_type" : "JAVA",
    "owner" : "admin",
    "owner_type" : "USER",
    "owner_auth_source_type" : "IAM",
    "class_name" : "a",
    "create_time" : "2022-12-09T01:50:56.000+00:00",
    "resource_uris" : [ {
      "type" : "JAR",
      "uri" : "obs://lakeformation-test/"
    }, {
      "type" : "FILE",
      "uri" : "obs://lakeformation-test/test3/"
    } ]
  } ],
  "datasets" : [ {
    "catalog_name" : "catalog",
    "catalog_id" : "string",
    "dataset_name" : "testfileset",
    "dataset_id" : "string",
    "description" : "this is a fileset",
    "storage_type" : "EXTERNAL",
    "dataset_format" : {
      "format" : "ROW",
      "content_types" : [ "PNG", "CSV" ]
    },
    "owner" : "testowner",
    "owner_type" : "USER",
    "owner_source" : "IAM",
    "location" : "obs://location/uri/",
    "properties" : {
      "additionalProp1" : "string",
      "additionalProp2" : "string",
      "additionalProp3" : "string"
    },
    "create_time" : "2024-02-28T08:28:23.288Z",
    "update_time" : "2024-02-28T08:28:23.288Z"
  } ]
}

状态码：400

Bad Request

{
  "error_code" : "common.01000001",
  "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException"
}

状态码：401

Unauthorized

{
  "error_code" : "APIG.1002",
  "error_msg" : "Incorrect token or token resolution failed"
}

状态码：403

Forbidden

{
  "error" : {
    "code" : "403",
    "message" : "X-Auth-Token is invalid in the request",
    "error_code" : null,
    "error_msg" : null,
    "title" : "Forbidden"
  },
  "error_code" : "403",
  "error_msg" : "X-Auth-Token is invalid in the request",
  "title" : "Forbidden"
}

状态码：404

Not Found

{
  "error_code" : "common.01000001",
  "error_msg" : "response status exception, code: 404"
}

状态码：408

Request Timeout

{
  "error_code" : "common.00000408",
  "error_msg" : "timeout exception occurred"
}

状态码：500

Internal Server Error

{
  "error_code" : "common.00000500",
  "error_msg" : "internal error"
}

状态码

状态码

描述

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

408

Request Timeout

500

Internal Server Error

错误码

请参见错误码。

父主题： 元数据管理

相关文档