For the complete documentation index, see llms.txt. This page is also available as Markdown.

Search Data Sources

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Endpoints and methods

Method
Path
Purpose

GET

/dataSource

Search for data sources.

GET

Get a data source based on the ID.

GET

Get data source based on the name.

GET

Get data source based on the short name.

GET

Get all users with the provided access level for this data source.

GET

Retrieves the visibilities, masking information, and filters that the passed in user has access to in the specified data source.

GET

Retrieves a summary of total records, total visibilities, and visibilities a given user has access to.

GET

Retrieves a summary of total records, total visibilities, and visibilities the current user has access to for a specified data source.

GET /dataSource

Search for data sources that you own or are authorized to see.

Required: For a data source to appear in the response, you must own the data source, the data source must be publicly visible, or you must have access to see the data source through the GOVERNANCE permission or a subscription policy

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/dataSource?size=2

Query parameters

Attribute
Description
Required

blobHandlerType

array[string] Describes the type of underlying blob handler that will be used with this data source (e.g., Custom, MS SQL).

No

subscription

array[string] The requesting user's subscription status: pending, owner, subscribed, not_subscribed, or expert.

No

status

array[string] The data source status: passed or failed.

No

tag

array[string] Filters data sources by tags associated with the data sources.

No

tagOperator

string Use with the tag attribute to search for data sources with multiple tags. Options are AND or OR.

No

tagModelTypes

string Use with the tag attribute to search for data sources with the tags applied to the datasource or the column.

No

searchText

string Searches for data source names using the provided string.

No

fuzzySearch

boolean If true, the search will ignore quotes and spaces.

No

column

array[string] Searches for data source column names.

No

connectionString

array[string] Searches by connection string.

No

schema

string Searches for data source schema.

No

nameOnly

boolean When true, searchText will only search data source names. Default is false.

No

idOnly

boolean When true, only returns the ID of the data source and the user's subscription status. count will be 0 in the response if idOnly is set to true.

No

dataSourceIds

array[integer] Searches for the provided data source IDs.

No

selectFields

array[string] This field accepts the values id, name, and columnEvolutionEnabled. When id or name are provided, the request will return only the ID or name of the data source and the subscription status. If columnEvolutionEnabled is provided, the response will also include information about the policies, policy conflicts, and workspaces associated with the data sources.

No

offset

integer Used in combination with size to fetch pages. Default is 0.

No

size

integer The number of results to return per page. Default is 10.

No

sortField

string Used to sort results by field, which must be createdAt, name, blobHandlerType, subscriptionStatus, id, status, policy, or editable.

No

sortOrder

string Sorts results by order, which must be asc or desc.

No

excludedProjects

array[integer] Filter out any data sources that belong to the specified projects.

No

ephemeral

boolean When true, returns ephemeral data sources.

No

clusterName

string The name of the remote cluster the data source is connected to.

No

mode

integer Specifies the query mode, which must be 0 (FULL) or 1 (COUNT).

No

globalPolicy

string Filter by data sources that have this Global Policy applied.

No

hostname

string Searches data sources by hostname.

No

determinePolicyConflicts

boolean When true, filters results to return the data sources with policy conflicts.

No

domainId

string Filter by data sources in the domain with this ID.

No

domainExclude

string When true, filters results to return the data sources in the domain of the provided ID.

No

domainsToExclude

array[string] Use with the domainExclude attribute to filter out data sources by the domains they are in.

No

disabled

boolean If true, only data sources that are disabled will be returned.

No

port

string Filter by data sources associated with a specific port.

No

metastoreId

string Filter by data sources with the specific metastore ID.

No

objectType

array[string] Filter by the specifc object type of the data source. Options include: table, view, volume, function, and model.

No

Response

Returns a list of data source objects for data sources you own or are authorized to see as hits and a count of all the data source objects that could be returned.

GET /dataSource/{dataSourceId}

Get a data source based on the ID.

Required: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the GOVERNANCE permission or a subscription policy

Path parameters

Attribute
Description
Required

dataSourceId

integer The data source ID .

Yes

Response

Returns a data source object.

GET /dataSource/name/{dataSourceName}

Get a data source based on the name.

Required: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the GOVERNANCE permission or a subscription policy

Path parameters

Attribute
Description
Required

dataSourceName

string The data source name.

Yes

Response

Returns a data source object.

GET /dataSource/sqlTableName/{shortName}

Get a data source based on the SQL table name.

Required: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the GOVERNANCE permission or a subscription policy

Path parameters

Attribute
Description
Required

shortName

string The data source SQL table name.

Yes

Response

Returns a data source object.

GET /dataSource/{dataSourceId}/access

Get all users with the provided access level for this data source.

Required: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the GOVERNANCE permission or a subscription policy

Path parameters

Attribute
Description
Required

dataSourceId

integer The data source ID .

Yes

Query parameters

Attribute
Description
Required

states

Array[string] The status levels to include when querying for user access.

No

approved

boolean Denotes whether the returned access objects should be approved.

No

searchText

string A string used to filter returned users. The query is executed with a wildcard prefix and suffix.

No

size

integer The number of results to return.

No

offset

integer The number of results to skip (for paging).

No

sortField

string The field on which to sort the result set.

No

sortOrder

string The order in which to sort the results.

No

expandGroups

boolean If true will return individual members of any group subscribed.

No

ignoreSystemGenerated

boolean If true, will not return system generated accounts.

No

filterBySchemaEvolution

boolean If true, will only return users who have the specified level of access across ALL data sources within the same schema evolution group as this one.

No

Response

Returns metadata about users with access to the data source.

Attribute
Description

count

integer The number of users with access to the data source.

users

string The metadata regarding the users with access to the data source.

GET /dataSource/{dataSourceId}/users/{profileId}/policyInfo

Retrieves the visibilities, masking information, and filters that the passed in user has access to in the specified data source.

Required Immuta permission: FETCH_POLICY_INFO

Path parameters

Attribute
Description
Required

dataSourceId

integer The data source ID .

Yes

profileId

integer The profile ID of the user.

Yes

Query parameters

Attribute
Description
Required

projectId

integer The project ID. If provided, this project will be used when evaluating the user's visibilities.

No

Response

Returns visibility, masking, and filter details for the specified user.

Attribute
Description

visibilities

array Details of the user's visibilities, including anyKey.

visibilityRuleApplies

boolean If true, a visibility rule exists and the user is not excepted from it.

masked

array Masking information for the data source, including metadata, name, type, and actionType.

additionalFilters

array Policy information for the data source, including customWhere, differentialPrivacy, eventTimeColumn, minimization, time, filterSeconds, and isOlderOrNewer.

GET /dataSource/{dataSourceId}/users/{profileId}/visibilityReport

Retrieves a summary of total records, total visibilities (the unique values contained in a column protected by a row-level security policy that allow Immuta to determine whether or not a user can see a given row if they possess an attribute that matches the visibility of that row), and visibilities a given user has access to.

Required: The global GOVERNANCE permission or be the data source owner

Path parameters

Attribute
Description
Required

dataSourceId

integer The data source ID .

Yes

profileId

integer The profile ID of the user.

Yes

Query parameters

Attribute
Description
Required

informationOnly

boolean If true, the query will just return information for the UI and will skip running some queries for ephemeral data sources.

No

includeNestedColumns

boolean If true, the query will return just information for the dictionary page, including the masking policies for nested columns.

No

Response

Returns a summary of records, visibilities, masking, and policy details for the specified user.

Attribute
Description

noVisibilities

boolean If true, the data source has no row-level security or purpose-based restriction policies applied to it.

dataSourceVisibilitiesCount

integer The total number of possible visibilities the given data source has.

userVisibilitiesCount

integer The number of visibilities the current user can see for the given data source.

masked

array Masking information for the data source, including metadata, name, type, and actionType.

dataSource

integer The data source ID.

dataSourceName

string The data source name.

additionalFilters

array Policy information for the data source, including customWhere, eventTimeColumn, minimization, time, filterSeconds, and isOlderOrNewer.

allowMaskedJoins

boolean If true the data source allows masked joins.

policySet

array Details about the policies on the data source.

GET /dataSource/{dataSourceId}/visibilityReport

Retrieves a summary of total records, total visibilities (the unique values contained in a column protected by a row-level security policy that allow Immuta to determine whether or not a user can see a given row if they possess an attribute that matches the visibility of that row), and visibilities the current user has access to for a specified data source.

Required: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the GOVERNANCE permission or a subscription policy

Path parameters

Attribute
Description
Required

dataSourceId

integer The data source ID.

Yes

Response

Returns a summary of records, visibilities, masking, and policy details for the current user.

Attribute
Description

noVisibilities

boolean If true, the data source has no row-level security or purpose-based restriction policies applied to it.

dataSourceVisibilitiesCount

integer The total number of possible visibilities the given data source has.

userVisibilitiesCount

integer The number of visibilities the current user can see for the given data source.

denialReason

string Reason the user was denied visibility.

masked

array Masking information for the data source, including metadata, name, type, and actionType.

dataSource

integer The data source ID.

dataSourceName

string The data source name.

additionalFilters

array Policy information for the data source, including customWhere, differentialPrivacy, eventTimeColumn, minimization, time, filterSeconds, and isOlderOrNewer.

allowMaskedJoins

boolean If true the data source allows masked joins.

policySet

array Details about the policies on the data source.

Data source object attributes

Attribute
Description

name

string The data source name.

recordFormat

string The data format of blobs in the data source, such as json, xml, html, or jpeg.

description

string The description of the data source.

policyHandler

object The policy handler details and policies enforced on the data source.

sqlSchemaName

string A string that represents this data source's schema name in Immuta.

sqlTableName

string The SQL table name in Immuta.

blobHandler

object Blob handler configuration for the data source (for example, url, optional ca, and manualDictionary).

blobHandlerType

string Describes the type of underlying blob handler that will be used with this data source (e.g., MS SQL).

createdBy

integer The ID of the profile creating the data source.

deleted

boolean If true, the data source was deleted.

type

string The data source type: queryable.

rowCount

integer The number of rows.

id

integer The data source ID.

statsExpiration

timestamp The time when the data source statistics (e.g., rowCount) expire and will need to be re-run.

policyHandlerType

string The type of policy handler applied to the data source: Builder.

subscriptionType

string The type of subscription policy on the data source. The type can be policy (which only allows users with specific groups or attributes to subscribe) or manual (which requires users to be manually added).

subscriptionPolicy

object Details about the subscription policy applied to the data source.

globalPolicies

string Details about the global policies applied to the data source.

status

string The data source health status.

statusInfo

object Details about the status of all the jobs and health checks that ran on the data source.

catalogMetadata

object Details about the connected external catalog.

workspace

integer The ID of the workspace the data is in.

seeded

boolean If true, the data source was system-generated.

schemaEvolutionId

string The ID for the schema project the data source is in.

columnEvolutionEnabled

boolean If true, the data source has schema monitoring and column detection on.

createdAt

timestamp The time the data source was created.

updatedAt

timestamp The time the data source was last updated.

dataObjectId

integer The ID of the data object associated with the data source.

legacyName

string The name of the data source before it was upgraded to connections.

dataObjectUniqueId

string The UUID for the data object associated with the data source.

parentIdPath

array The list of UUIDs for the parent data objects (e.g., database, schema, etc.) that contain this data source.

namePath

array The list of names for the parent data objects (e.g., database, schema, etc.) that contain this data source.

legacyObjectType

string The type of data object. Options include: BASE TABLE, ICEBERG TABLE, VIEW, MATERIALIZED VIEW, MANAGED, STREAMING_TABLE, MATERIALIZED_VIEW, VOLUME_MANAGED, VOLUME_EXTERNAL, GOVERNED, and EXTERNAL_TABLE.

connectionKey

string The connection key (or display name) for the connection the data source comes from.

subscribedAsUser

boolean If true, the user who made the API request is subscribed to the data source.

subscriptionContext

string Description of why the user does or does not have access to the data source. Optional and may not be available.

subscriptionId

integer An ID of the record associated with the subscription of the user who made the API request to the data source.

acknowledgeRequired

boolean If true, users must acknowledge the policy before they can subscribe to the data source.

subscriptionStatus

string The subscription status to the data source of the user who made the API request. Accepted statuses are owner, subscribed, or unsubscribed.

requestedState

string The subscription state of the user making the API request if they manually requested access to the data source in the Govern app.

approved

boolean If true, the user's requested subscription status was approved.

subscriptionExpiration

timestamp The time that the user who made the API request subscription to the data source will expire.

filterId

string The ID of the search filter applied to this data source, if available.

accessGrant

string The type of access granted to the user making the API request. Options include: READ and WRITE.

accessPolicies

object Details about the access policies applied to the data source.

subscribers

integer The number of Immuta users subscribed to the data source.

tags

object Details about the tags applied to this data source.

fingerprintCreatedAt

timestamp The last time the data source fingerprint was generated, if available.

remoteDataObject

object Details about the remote data object including the name and path.

Last updated

Was this helpful?