Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

GetUnfilteredTableMetadata

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.

Request Syntax


{
   "AuditContext": { 
      "AdditionalAuditContext": "string",
      "AllColumnsRequested": boolean,
      "RequestedColumns": [ "string" ]
   },
   "CatalogId": "string",
   "DatabaseName": "string",
   "Name": "string",
   "ParentResourceArn": "string",
   "Permissions": [ "string" ],
   "QuerySessionContext": { 
      "AdditionalContext": { 
         "string" : "string" 
      },
      "ClusterId": "string",
      "QueryAuthorizationId": "string",
      "QueryId": "string",
      "QueryStartTime": number
   },
   "Region": "string",
   "RootResourceArn": "string",
   "SupportedDialect": { 
      "Dialect": "string",
      "DialectVersion": "string"
   },
   "SupportedPermissionTypes": [ "string" ]
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

AuditContext

A structure containing Lake Formation audit context information.

Type: AuditContext object

Required: No

CatalogId

The catalog ID where the table resides.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*

Required: Yes

DatabaseName

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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*

Required: Yes

Name

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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*

Required: Yes

ParentResourceArn

The resource ARN of the view.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

Permissions

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

Type: Array of strings

Required: No

QuerySessionContext

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

Type: QuerySessionContext object

Required: No

Region

Specified only if the base tables belong to a different AWS Region.

Type: String

Length Constraints: Maximum length of 1024.

Required: No

RootResourceArn

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

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

SupportedDialect

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

Type: SupportedDialect object

Required: No

SupportedPermissionTypes

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.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 255 items.

Valid Values: COLUMN_PERMISSION | CELL_FILTER_PERMISSION | NESTED_PERMISSION | NESTED_CELL_PERMISSION

Required: Yes

Response Syntax


{
   "AuthorizedColumns": [ "string" ],
   "CellFilters": [ 
      { 
         "ColumnName": "string",
         "RowFilterExpression": "string"
      }
   ],
   "IsMultiDialectView": boolean,
   "IsProtected": boolean,
   "IsRegisteredWithLakeFormation": boolean,
   "Permissions": [ "string" ],
   "QueryAuthorizationId": "string",
   "ResourceArn": "string",
   "RowFilter": "string",
   "Table": { 
      "CatalogId": "string",
      "CreatedBy": "string",
      "CreateTime": number,
      "DatabaseName": "string",
      "Description": "string",
      "FederatedTable": { 
         "ConnectionName": "string",
         "DatabaseIdentifier": "string",
         "Identifier": "string"
      },
      "IsMultiDialectView": boolean,
      "IsRegisteredWithLakeFormation": boolean,
      "LastAccessTime": number,
      "LastAnalyzedTime": number,
      "Name": "string",
      "Owner": "string",
      "Parameters": { 
         "string" : "string" 
      },
      "PartitionKeys": [ 
         { 
            "Comment": "string",
            "Name": "string",
            "Parameters": { 
               "string" : "string" 
            },
            "Type": "string"
         }
      ],
      "Retention": number,
      "Status": { 
         "Action": "string",
         "Details": { 
            "RequestedChange": "Table",
            "ViewValidations": [ 
               { 
                  "Dialect": "string",
                  "DialectVersion": "string",
                  "Error": { 
                     "ErrorCode": "string",
                     "ErrorMessage": "string"
                  },
                  "State": "string",
                  "UpdateTime": number,
                  "ViewValidationText": "string"
               }
            ]
         },
         "Error": { 
            "ErrorCode": "string",
            "ErrorMessage": "string"
         },
         "RequestedBy": "string",
         "RequestTime": number,
         "State": "string",
         "UpdatedBy": "string",
         "UpdateTime": number
      },
      "StorageDescriptor": { 
         "AdditionalLocations": [ "string" ],
         "BucketColumns": [ "string" ],
         "Columns": [ 
            { 
               "Comment": "string",
               "Name": "string",
               "Parameters": { 
                  "string" : "string" 
               },
               "Type": "string"
            }
         ],
         "Compressed": boolean,
         "InputFormat": "string",
         "Location": "string",
         "NumberOfBuckets": number,
         "OutputFormat": "string",
         "Parameters": { 
            "string" : "string" 
         },
         "SchemaReference": { 
            "SchemaId": { 
               "RegistryName": "string",
               "SchemaArn": "string",
               "SchemaName": "string"
            },
            "SchemaVersionId": "string",
            "SchemaVersionNumber": number
         },
         "SerdeInfo": { 
            "Name": "string",
            "Parameters": { 
               "string" : "string" 
            },
            "SerializationLibrary": "string"
         },
         "SkewedInfo": { 
            "SkewedColumnNames": [ "string" ],
            "SkewedColumnValueLocationMaps": { 
               "string" : "string" 
            },
            "SkewedColumnValues": [ "string" ]
         },
         "SortColumns": [ 
            { 
               "Column": "string",
               "SortOrder": number
            }
         ],
         "StoredAsSubDirectories": boolean
      },
      "TableType": "string",
      "TargetTable": { 
         "CatalogId": "string",
         "DatabaseName": "string",
         "Name": "string",
         "Region": "string"
      },
      "UpdateTime": number,
      "VersionId": "string",
      "ViewDefinition": { 
         "Definer": "string",
         "IsProtected": boolean,
         "Representations": [ 
            { 
               "Dialect": "string",
               "DialectVersion": "string",
               "IsStale": boolean,
               "ValidationConnection": "string",
               "ViewExpandedText": "string",
               "ViewOriginalText": "string"
            }
         ],
         "SubObjects": [ "string" ]
      },
      "ViewExpandedText": "string",
      "ViewOriginalText": "string"
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

AuthorizedColumns

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

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*

CellFilters

A list of column row filters.

Type: Array of ColumnRowFilter objects

IsMultiDialectView

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

Type: Boolean

IsProtected

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.

Type: Boolean

IsRegisteredWithLakeFormation

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

Type: Boolean

Permissions

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

Type: Array of strings

QueryAuthorizationId

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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*

ResourceArn

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

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

RowFilter

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.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Table

A Table object containing the table metadata.

Type: Table object

Errors

For information about the errors that are common to all actions, see Common Errors.

EntityNotFoundException

A specified entity does not exist

HTTP Status Code: 400

FederationSourceException

A federation source failed.

HTTP Status Code: 400

FederationSourceRetryableException

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

HTTP Status Code: 400

GlueEncryptionException

An encryption operation failed.

HTTP Status Code: 400

InternalServiceException

An internal service error occurred.

HTTP Status Code: 500

InvalidInputException

The input provided was not valid.

HTTP Status Code: 400

OperationTimeoutException

The operation timed out.

HTTP Status Code: 400

PermissionTypeMismatchException

The operation timed out.

HTTP Status Code: 400