GetUnfilteredTableMetadataCommand

Suggest an Edit

Allows a third-party analytical engine to retrieve unfiltered table metadata from the Data Catalog.

For IAM authorization, the public IAM action associated with this API is glue:GetTable.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { GlueClient, GetUnfilteredTableMetadataCommand } from "@aws-sdk/client-glue"; // ES Modules import
// const { GlueClient, GetUnfilteredTableMetadataCommand } = require("@aws-sdk/client-glue"); // CommonJS import
const client = new GlueClient(config);
const input = { // GetUnfilteredTableMetadataRequest
  Region: "STRING_VALUE",
  CatalogId: "STRING_VALUE", // required
  DatabaseName: "STRING_VALUE", // required
  Name: "STRING_VALUE", // required
  AuditContext: { // AuditContext
    AdditionalAuditContext: "STRING_VALUE",
    RequestedColumns: [ // AuditColumnNamesList
      "STRING_VALUE",
    ],
    AllColumnsRequested: true || false,
  },
  SupportedPermissionTypes: [ // PermissionTypeList // required
    "COLUMN_PERMISSION" || "CELL_FILTER_PERMISSION" || "NESTED_PERMISSION" || "NESTED_CELL_PERMISSION",
  ],
  ParentResourceArn: "STRING_VALUE",
  RootResourceArn: "STRING_VALUE",
  SupportedDialect: { // SupportedDialect
    Dialect: "REDSHIFT" || "ATHENA" || "SPARK",
    DialectVersion: "STRING_VALUE",
  },
  Permissions: [ // PermissionList
    "ALL" || "SELECT" || "ALTER" || "DROP" || "DELETE" || "INSERT" || "CREATE_DATABASE" || "CREATE_TABLE" || "DATA_LOCATION_ACCESS",
  ],
  QuerySessionContext: { // QuerySessionContext
    QueryId: "STRING_VALUE",
    QueryStartTime: new Date("TIMESTAMP"),
    ClusterId: "STRING_VALUE",
    QueryAuthorizationId: "STRING_VALUE",
    AdditionalContext: { // AdditionalContextMap
      "<keys>": "STRING_VALUE",
    },
  },
};
const command = new GetUnfilteredTableMetadataCommand(input);
const response = await client.send(command);
// { // GetUnfilteredTableMetadataResponse
//   Table: { // Table
//     Name: "STRING_VALUE", // required
//     DatabaseName: "STRING_VALUE",
//     Description: "STRING_VALUE",
//     Owner: "STRING_VALUE",
//     CreateTime: new Date("TIMESTAMP"),
//     UpdateTime: new Date("TIMESTAMP"),
//     LastAccessTime: new Date("TIMESTAMP"),
//     LastAnalyzedTime: new Date("TIMESTAMP"),
//     Retention: Number("int"),
//     StorageDescriptor: { // StorageDescriptor
//       Columns: [ // ColumnList
//         { // Column
//           Name: "STRING_VALUE", // required
//           Type: "STRING_VALUE",
//           Comment: "STRING_VALUE",
//           Parameters: { // ParametersMap
//             "<keys>": "STRING_VALUE",
//           },
//         },
//       ],
//       Location: "STRING_VALUE",
//       AdditionalLocations: [ // LocationStringList
//         "STRING_VALUE",
//       ],
//       InputFormat: "STRING_VALUE",
//       OutputFormat: "STRING_VALUE",
//       Compressed: true || false,
//       NumberOfBuckets: Number("int"),
//       SerdeInfo: { // SerDeInfo
//         Name: "STRING_VALUE",
//         SerializationLibrary: "STRING_VALUE",
//         Parameters: {
//           "<keys>": "STRING_VALUE",
//         },
//       },
//       BucketColumns: [ // NameStringList
//         "STRING_VALUE",
//       ],
//       SortColumns: [ // OrderList
//         { // Order
//           Column: "STRING_VALUE", // required
//           SortOrder: Number("int"), // required
//         },
//       ],
//       Parameters: "<ParametersMap>",
//       SkewedInfo: { // SkewedInfo
//         SkewedColumnNames: [
//           "STRING_VALUE",
//         ],
//         SkewedColumnValues: [ // ColumnValueStringList
//           "STRING_VALUE",
//         ],
//         SkewedColumnValueLocationMaps: { // LocationMap
//           "<keys>": "STRING_VALUE",
//         },
//       },
//       StoredAsSubDirectories: true || false,
//       SchemaReference: { // SchemaReference
//         SchemaId: { // SchemaId
//           SchemaArn: "STRING_VALUE",
//           SchemaName: "STRING_VALUE",
//           RegistryName: "STRING_VALUE",
//         },
//         SchemaVersionId: "STRING_VALUE",
//         SchemaVersionNumber: Number("long"),
//       },
//     },
//     PartitionKeys: [
//       {
//         Name: "STRING_VALUE", // required
//         Type: "STRING_VALUE",
//         Comment: "STRING_VALUE",
//         Parameters: "<ParametersMap>",
//       },
//     ],
//     ViewOriginalText: "STRING_VALUE",
//     ViewExpandedText: "STRING_VALUE",
//     TableType: "STRING_VALUE",
//     Parameters: "<ParametersMap>",
//     CreatedBy: "STRING_VALUE",
//     IsRegisteredWithLakeFormation: true || false,
//     TargetTable: { // TableIdentifier
//       CatalogId: "STRING_VALUE",
//       DatabaseName: "STRING_VALUE",
//       Name: "STRING_VALUE",
//       Region: "STRING_VALUE",
//     },
//     CatalogId: "STRING_VALUE",
//     VersionId: "STRING_VALUE",
//     FederatedTable: { // FederatedTable
//       Identifier: "STRING_VALUE",
//       DatabaseIdentifier: "STRING_VALUE",
//       ConnectionName: "STRING_VALUE",
//     },
//     ViewDefinition: { // ViewDefinition
//       IsProtected: true || false,
//       Definer: "STRING_VALUE",
//       SubObjects: [ // ViewSubObjectsList
//         "STRING_VALUE",
//       ],
//       Representations: [ // ViewRepresentationList
//         { // ViewRepresentation
//           Dialect: "REDSHIFT" || "ATHENA" || "SPARK",
//           DialectVersion: "STRING_VALUE",
//           ViewOriginalText: "STRING_VALUE",
//           ViewExpandedText: "STRING_VALUE",
//           ValidationConnection: "STRING_VALUE",
//           IsStale: true || false,
//         },
//       ],
//     },
//     IsMultiDialectView: true || false,
//     Status: { // TableStatus
//       RequestedBy: "STRING_VALUE",
//       UpdatedBy: "STRING_VALUE",
//       RequestTime: new Date("TIMESTAMP"),
//       UpdateTime: new Date("TIMESTAMP"),
//       Action: "UPDATE" || "CREATE",
//       State: "QUEUED" || "IN_PROGRESS" || "SUCCESS" || "STOPPED" || "FAILED",
//       Error: { // ErrorDetail
//         ErrorCode: "STRING_VALUE",
//         ErrorMessage: "STRING_VALUE",
//       },
//       Details: { // StatusDetails
//         RequestedChange: {
//           Name: "STRING_VALUE", // required
//           DatabaseName: "STRING_VALUE",
//           Description: "STRING_VALUE",
//           Owner: "STRING_VALUE",
//           CreateTime: new Date("TIMESTAMP"),
//           UpdateTime: new Date("TIMESTAMP"),
//           LastAccessTime: new Date("TIMESTAMP"),
//           LastAnalyzedTime: new Date("TIMESTAMP"),
//           Retention: Number("int"),
//           StorageDescriptor: {
//             Columns: "<ColumnList>",
//             Location: "STRING_VALUE",
//             AdditionalLocations: [
//               "STRING_VALUE",
//             ],
//             InputFormat: "STRING_VALUE",
//             OutputFormat: "STRING_VALUE",
//             Compressed: true || false,
//             NumberOfBuckets: Number("int"),
//             SerdeInfo: {
//               Name: "STRING_VALUE",
//               SerializationLibrary: "STRING_VALUE",
//               Parameters: "<ParametersMap>",
//             },
//             BucketColumns: "<NameStringList>",
//             SortColumns: [
//               {
//                 Column: "STRING_VALUE", // required
//                 SortOrder: Number("int"), // required
//               },
//             ],
//             Parameters: "<ParametersMap>",
//             SkewedInfo: {
//               SkewedColumnNames: "<NameStringList>",
//               SkewedColumnValues: [
//                 "STRING_VALUE",
//               ],
//               SkewedColumnValueLocationMaps: {
//                 "<keys>": "STRING_VALUE",
//               },
//             },
//             StoredAsSubDirectories: true || false,
//             SchemaReference: {
//               SchemaId: {
//                 SchemaArn: "STRING_VALUE",
//                 SchemaName: "STRING_VALUE",
//                 RegistryName: "STRING_VALUE",
//               },
//               SchemaVersionId: "STRING_VALUE",
//               SchemaVersionNumber: Number("long"),
//             },
//           },
//           PartitionKeys: "<ColumnList>",
//           ViewOriginalText: "STRING_VALUE",
//           ViewExpandedText: "STRING_VALUE",
//           TableType: "STRING_VALUE",
//           Parameters: "<ParametersMap>",
//           CreatedBy: "STRING_VALUE",
//           IsRegisteredWithLakeFormation: true || false,
//           TargetTable: {
//             CatalogId: "STRING_VALUE",
//             DatabaseName: "STRING_VALUE",
//             Name: "STRING_VALUE",
//             Region: "STRING_VALUE",
//           },
//           CatalogId: "STRING_VALUE",
//           VersionId: "STRING_VALUE",
//           FederatedTable: {
//             Identifier: "STRING_VALUE",
//             DatabaseIdentifier: "STRING_VALUE",
//             ConnectionName: "STRING_VALUE",
//           },
//           ViewDefinition: {
//             IsProtected: true || false,
//             Definer: "STRING_VALUE",
//             SubObjects: [
//               "STRING_VALUE",
//             ],
//             Representations: [
//               {
//                 Dialect: "REDSHIFT" || "ATHENA" || "SPARK",
//                 DialectVersion: "STRING_VALUE",
//                 ViewOriginalText: "STRING_VALUE",
//                 ViewExpandedText: "STRING_VALUE",
//                 ValidationConnection: "STRING_VALUE",
//                 IsStale: true || false,
//               },
//             ],
//           },
//           IsMultiDialectView: true || false,
//           Status: {
//             RequestedBy: "STRING_VALUE",
//             UpdatedBy: "STRING_VALUE",
//             RequestTime: new Date("TIMESTAMP"),
//             UpdateTime: new Date("TIMESTAMP"),
//             Action: "UPDATE" || "CREATE",
//             State: "QUEUED" || "IN_PROGRESS" || "SUCCESS" || "STOPPED" || "FAILED",
//             Error: {
//               ErrorCode: "STRING_VALUE",
//               ErrorMessage: "STRING_VALUE",
//             },
//             Details: {
//               RequestedChange: "<Table>",
//               ViewValidations: [ // ViewValidationList
//                 { // ViewValidation
//                   Dialect: "REDSHIFT" || "ATHENA" || "SPARK",
//                   DialectVersion: "STRING_VALUE",
//                   ViewValidationText: "STRING_VALUE",
//                   UpdateTime: new Date("TIMESTAMP"),
//                   State: "QUEUED" || "IN_PROGRESS" || "SUCCESS" || "STOPPED" || "FAILED",
//                   Error: "<ErrorDetail>",
//                 },
//               ],
//             },
//           },
//         },
//         ViewValidations: [
//           {
//             Dialect: "REDSHIFT" || "ATHENA" || "SPARK",
//             DialectVersion: "STRING_VALUE",
//             ViewValidationText: "STRING_VALUE",
//             UpdateTime: new Date("TIMESTAMP"),
//             State: "QUEUED" || "IN_PROGRESS" || "SUCCESS" || "STOPPED" || "FAILED",
//             Error: "<ErrorDetail>",
//           },
//         ],
//       },
//     },
//   },
//   AuthorizedColumns: "<NameStringList>",
//   IsRegisteredWithLakeFormation: true || false,
//   CellFilters: [ // ColumnRowFilterList
//     { // ColumnRowFilter
//       ColumnName: "STRING_VALUE",
//       RowFilterExpression: "STRING_VALUE",
//     },
//   ],
//   QueryAuthorizationId: "STRING_VALUE",
//   IsMultiDialectView: true || false,
//   ResourceArn: "STRING_VALUE",
//   IsProtected: true || false,
//   Permissions: [ // PermissionList
//     "ALL" || "SELECT" || "ALTER" || "DROP" || "DELETE" || "INSERT" || "CREATE_DATABASE" || "CREATE_TABLE" || "DATA_LOCATION_ACCESS",
//   ],
//   RowFilter: "STRING_VALUE",
// };

GetUnfilteredTableMetadataCommand Input

See GetUnfilteredTableMetadataCommandInput for more details

Parameter
Type
Description
CatalogId
Required
string | undefined

The catalog ID where the table resides.

DatabaseName
Required
string | undefined

(Required) Specifies the name of a database that contains the table.

Name
Required
string | undefined

(Required) Specifies the name of a table for which you are requesting metadata.

SupportedPermissionTypes
Required
PermissionType[] | undefined

Indicates the level of filtering a third-party analytical engine is capable of enforcing when calling the GetUnfilteredTableMetadata API operation. Accepted values are:

  • COLUMN_PERMISSION - Column permissions ensure that users can access only specific columns in the table. If there are particular columns contain sensitive data, data lake administrators can define column filters that exclude access to specific columns.

  • CELL_FILTER_PERMISSION - Cell-level filtering combines column filtering (include or exclude columns) and row filter expressions to restrict access to individual elements in the table.

  • NESTED_PERMISSION - Nested permissions combines cell-level filtering and nested column filtering to restrict access to columns and/or nested columns in specific rows based on row filter expressions.

  • NESTED_CELL_PERMISSION - Nested cell permissions combines nested permission with nested cell-level filtering. This allows different subsets of nested columns to be restricted based on an array of row filter expressions.

Note: Each of these permission types follows a hierarchical order where each subsequent permission type includes all permission of the previous type.

Important: If you provide a supported permission type that doesn't match the user's level of permissions on the table, then Lake Formation raises an exception. For example, if the third-party engine calling the GetUnfilteredTableMetadata operation can enforce only column-level filtering, and the user has nested cell filtering applied on the table, Lake Formation throws an exception, and will not return unfiltered table metadata and data access credentials.

AuditContext
AuditContext | undefined

A structure containing Lake Formation audit context information.

ParentResourceArn
string | undefined

The resource ARN of the view.

Permissions
Permission[] | undefined

The Lake Formation data permissions of the caller on the table. Used to authorize the call when no view context is found.

QuerySessionContext
QuerySessionContext | undefined

A structure used as a protocol between query engines and Lake Formation or Glue. Contains both a Lake Formation generated authorization identifier and information from the request's authorization context.

Region
string | undefined

Specified only if the base tables belong to a different Amazon Web Services Region.

RootResourceArn
string | undefined

The resource ARN of the root view in a chain of nested views.

SupportedDialect
SupportedDialect | undefined

A structure specifying the dialect and dialect version used by the query engine.

GetUnfilteredTableMetadataCommand Output

See GetUnfilteredTableMetadataCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
AuthorizedColumns
string[] | undefined

A list of column names that the user has been granted access to.

CellFilters
ColumnRowFilter[] | undefined

A list of column row filters.

IsMultiDialectView
boolean | undefined

Specifies whether the view supports the SQL dialects of one or more different query engines and can therefore be read by those engines.

IsProtected
boolean | undefined

A flag that instructs the engine not to push user-provided operations into the logical plan of the view during query planning. However, if set this flag does not guarantee that the engine will comply. Refer to the engine's documentation to understand the guarantees provided, if any.

IsRegisteredWithLakeFormation
boolean | undefined

A Boolean value that indicates whether the partition location is registered with Lake Formation.

Permissions
Permission[] | undefined

The Lake Formation data permissions of the caller on the table. Used to authorize the call when no view context is found.

QueryAuthorizationId
string | undefined

A cryptographically generated query identifier generated by Glue or Lake Formation.

ResourceArn
string | undefined

The resource ARN of the parent resource extracted from the request.

RowFilter
string | undefined

The filter that applies to the table. For example when applying the filter in SQL, it would go in the WHERE clause and can be evaluated by using an AND operator with any other predicates applied by the user querying the table.

Table
Table | undefined

A Table object containing the table metadata.

Throws

Name
Fault
Details
EntityNotFoundException
client

A specified entity does not exist

FederationSourceException
client

A federation source failed.

FederationSourceRetryableException
client

A federation source failed, but the operation may be retried.

GlueEncryptionException
client

An encryption operation failed.

InternalServiceException
server

An internal service error occurred.

InvalidInputException
client

The input provided was not valid.

OperationTimeoutException
client

The operation timed out.

PermissionTypeMismatchException
client

The operation timed out.

GlueServiceException
Base exception class for all service exceptions from Glue service.