## Link knowledge files and assets

URL: https://docs.atlan.com/product/capabilities/build-apps/sdks/python/how-tos/link-knowledge-files

> Link knowledge files to assets in Atlan using KnowledgeFile and the Python SDK (pyatlan). Append, replace, or remove linked files programmatically, and read the files linked to an asset.

# KnowledgeFile: Link knowledge files to assets

Use `KnowledgeFile` in the Atlan Python SDK to programmatically link [knowledge files](https://docs.atlan.com/llms/governance/knowledge-folders/llms.txt) to assets. A linked file appears on the asset's profile, and the Description and README agents read it the next time they enrich that asset. See [Link knowledge files to assets](https://docs.atlan.com/llms/governance/knowledge-folders/link-knowledge-files-to-assets/llms.txt) for what linking changes in the product.

A knowledge file can be linked to any asset type. The link lives on the asset side, in its `knowledgeLinkedFiles` relationship.

> **Note**
>
> The `knowledge_linked_files` attribute is available from pyatlan 11.2.0. The `append_knowledge_files`, `replace_knowledge_files`, and `remove_knowledge_files` methods are available in releases after 11.2.0.

## Prerequisites

Before you begin, make sure you have:

- The Python SDK [set up](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) with an API token that can update the target assets
- pyatlan 11.2.0 or later (see the note earlier in this page for the linking methods)
- The `qualified_name` or GUID of the asset to link, and the GUIDs of the knowledge files. Knowledge files are uploaded through [knowledge folders](https://docs.atlan.com/llms/governance/knowledge-folders/create-knowledge-folder/llms.txt); find their GUIDs with a [search](https://docs.atlan.com/llms/platform/python/search-assets/llms.txt) on the `KnowledgeFile` type

## Append knowledge files to asset

To link more knowledge files to an [asset](https://docs.atlan.com/llms/platform/python/build-your-first-metadata-workflow/llms.txt), without changing any of the files already linked to it:

### Python

```python showLineNumbers title="Append knowledge files to an asset"
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import KnowledgeFile, Table

client = AtlanClient()
table = client.asset.append_knowledge_files( # (1)
 asset_type=Table, # (2)
 qualified_name="default/snowflake/1657037873/SAMPLE_DATA/FOOD_BEVERAGE/ORDER_ANALYSIS", # (3)
 files=[KnowledgeFile.ref_by_guid(guid="b4113341-251b-4adc-81fb-2420501c30e6"), # (4)
 KnowledgeFile.ref_by_guid(guid="b267858d-8316-4c41-a56a-6e9b840cef4a")]
) # (5)
```

1. Use the `asset.append_knowledge_files()` method, which constructs the necessary
request and calls the necessary APIs to link the files all-in-one.
2. The `asset_type` of the asset on which to link the files.
3. The `qualified_name` of the asset on which to link the files.
 - Note: Alternatively the parameter name `guid` can be
 specified along with the `guid` of the asset on which to link the files.
4. A list of knowledge file references. Each reference can be to a file by its GUID
or its `qualified_name`. At the completion of this code, the files in this list are
*added to* any other files already linked to the asset. Linking a file that's
already linked is a no-op.
5. The `asset` returned by this call is a minimal asset and won't contain
any linked files. If you need an `asset` which contains them, retrieve it via
the `asset.get_by_guid` or `asset.get_by_qualified_name` methods, or see
[Read linked knowledge files](#read-linked-knowledge-files).

### Raw REST API

```json showLineNumbers title="POST /api/meta/entity/bulk"
{
 "entities": [ // (1)
 {
 "typeName": "Table", // (2)
 "attributes": {
 "name": "ORDER_ANALYSIS", // (3)
 "qualifiedName": "default/snowflake/1657037873/SAMPLE_DATA/FOOD_BEVERAGE/ORDER_ANALYSIS" // (4)
 },
 "appendRelationshipAttributes": { // (5)
 "knowledgeLinkedFiles": [
 {
 "typeName": "KnowledgeFile",
 "guid": "b4113341-251b-4adc-81fb-2420501c30e6"
 },
 {
 "typeName": "KnowledgeFile",
 "guid": "b267858d-8316-4c41-a56a-6e9b840cef4a"
 }
 ]
 }
 }
 ]
}
```

1. All assets must be wrapped in an `entities` array.
2. You must provide the exact type name for the asset (case-sensitive).
3. You must provide the exact name of the asset (case-sensitive).
4. You must provide the exact `qualifiedName` of the asset (case-sensitive).
5. Provide the files to link under `appendRelationshipAttributes.knowledgeLinkedFiles`. Each reference must include the `typeName` (always `KnowledgeFile`) and `guid` of the file. Files already linked to the asset stay linked, so you don't need to retrieve the asset first.

## Replace knowledge files on asset

To replace all the knowledge files linked to an asset, meaning any not specified in the request are unlinked from the asset:

### Python

```python showLineNumbers title="Replace knowledge files on an asset"
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import KnowledgeFile, Table

client = AtlanClient()
table = client.asset.replace_knowledge_files( # (1)
 asset_type=Table, # (2)
 qualified_name="default/snowflake/1657037873/SAMPLE_DATA/FOOD_BEVERAGE/ORDER_ANALYSIS", # (3)
 files=[KnowledgeFile.ref_by_guid(guid="b4113341-251b-4adc-81fb-2420501c30e6")] # (4)
) # (5)
```

1. Use the `asset.replace_knowledge_files()` method, which constructs the necessary
request and calls the necessary APIs to replace the linked files all-in-one.
2. The `asset_type` of the asset on which to replace the files.
3. The `qualified_name` of the asset on which to replace the files.
 - Note: Alternatively the parameter name `guid` can be
 specified along with the `guid` of the asset.
4. A list of knowledge file references. After the completion of this code, only the
files in this list are linked to the asset. Pass an empty list to unlink every
file from the asset.
5. The `asset` returned by this call is a minimal asset and won't contain
any linked files.

### Raw REST API

```json showLineNumbers title="POST /api/meta/entity/bulk"
{
 "entities": [ // (1)
 {
 "typeName": "Table", // (2)
 "attributes": {
 "name": "ORDER_ANALYSIS", // (3)
 "qualifiedName": "default/snowflake/1657037873/SAMPLE_DATA/FOOD_BEVERAGE/ORDER_ANALYSIS" // (4)
 },
 "relationshipAttributes": { // (5)
 "knowledgeLinkedFiles": [
 {
 "typeName": "KnowledgeFile",
 "guid": "b4113341-251b-4adc-81fb-2420501c30e6"
 }
 ]
 }
 }
 ]
}
```

1. All assets must be wrapped in an `entities` array.
2. You must provide the exact type name for the asset (case-sensitive).
3. You must provide the exact name of the asset (case-sensitive).
4. You must provide the exact `qualifiedName` of the asset (case-sensitive).
5. Provide the full set of files to link under `relationshipAttributes.knowledgeLinkedFiles`. After the completion of this call, only the files in this list are linked to the asset. An empty array unlinks every file.

## Remove knowledge files from asset

To unlink some knowledge files from an asset, without unlinking all of the files on the asset:

### Python

```python showLineNumbers title="Remove knowledge files from an asset"
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import KnowledgeFile, Table

client = AtlanClient()
table = client.asset.remove_knowledge_files( # (1)
 asset_type=Table, # (2)
 qualified_name="default/snowflake/1657037873/SAMPLE_DATA/FOOD_BEVERAGE/ORDER_ANALYSIS", # (3)
 files=[KnowledgeFile.ref_by_guid(guid="b4113341-251b-4adc-81fb-2420501c30e6")] # (4)
)
```

1. Use the `asset.remove_knowledge_files()` method, which constructs the necessary
request and calls the necessary APIs to unlink the files all-in-one.
2. The `asset_type` of the asset from which to unlink the files.
3. The `qualified_name` of the asset from which to unlink the files.
 - Note: Alternatively the parameter name `guid` can be
 specified along with the `guid` of the asset.
4. A list of knowledge file references, by GUID. At the completion of this code, the
files in this list are *unlinked from* the asset. Other linked files stay linked.
Unlinking a file doesn't delete the knowledge file.

### Raw REST API

```json showLineNumbers title="POST /api/meta/entity/bulk"
{
 "entities": [ // (1)
 {
 "typeName": "Table", // (2)
 "attributes": {
 "name": "ORDER_ANALYSIS", // (3)
 "qualifiedName": "default/snowflake/1657037873/SAMPLE_DATA/FOOD_BEVERAGE/ORDER_ANALYSIS" // (4)
 },
 "removeRelationshipAttributes": { // (5)
 "knowledgeLinkedFiles": [
 {
 "typeName": "KnowledgeFile",
 "guid": "b4113341-251b-4adc-81fb-2420501c30e6"
 }
 ]
 }
 }
 ]
}
```

1. All assets must be wrapped in an `entities` array.
2. You must provide the exact type name for the asset (case-sensitive).
3. You must provide the exact name of the asset (case-sensitive).
4. You must provide the exact `qualifiedName` of the asset (case-sensitive).
5. Provide the files to unlink under `removeRelationshipAttributes.knowledgeLinkedFiles`. Each reference must include the `typeName` (always `KnowledgeFile`) and `guid` of the file.

## Read linked knowledge files

Linked files are a relationship on the asset, so you read them the same way as any other relationship: include `knowledge_linked_files` on a search, or retrieve the asset.

### Python

```python showLineNumbers title="Read the knowledge files linked to an asset"
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import Asset, KnowledgeFile, Table
from pyatlan.model.fluent_search import FluentSearch

client = AtlanClient()
request = (
 FluentSearch()
 .where(FluentSearch.active_assets()) # (1)
 .where(FluentSearch.asset_type(Table))
 .where(Table.QUALIFIED_NAME.eq("default/snowflake/1657037873/SAMPLE_DATA/FOOD_BEVERAGE/ORDER_ANALYSIS"))
 .include_on_results(Asset.KNOWLEDGE_LINKED_FILES) # (2)
 .include_on_relations(KnowledgeFile.NAME) # (3)
).to_request()

for table in client.asset.search(request):
 for file in table.knowledge_linked_files or []: # (4)
 print(file.guid, file.name)
```

1. Restrict the search to active assets.
2. Include the `knowledge_linked_files` relationship on each result.
3. Include the file's `name` on the related `KnowledgeFile` objects, so you don't need a second lookup to display them.
4. `knowledge_linked_files` is `None` when the asset has no linked files.

### Raw REST API

```json showLineNumbers title="POST /api/meta/search/indexsearch"
{
 "dsl": {
 "query": {
 "bool": {
 "filter": [
 { "term": { "__state": { "value": "ACTIVE" } } },
 { "term": { "__typeName.keyword": { "value": "Table" } } },
 { "term": { "qualifiedName": { "value": "default/snowflake/1657037873/SAMPLE_DATA/FOOD_BEVERAGE/ORDER_ANALYSIS" } } }
 ]
 }
 }
 },
 "attributes": ["knowledgeLinkedFiles"], // (1)
 "relationAttributes": ["name"] // (2)
}
```

1. Request the `knowledgeLinkedFiles` relationship on each result.
2. Request the `name` of each related knowledge file.

## See also

- [Link knowledge files to assets](https://docs.atlan.com/llms/governance/knowledge-folders/link-knowledge-files-to-assets/llms.txt): the same link from the product UI, and how linked files change enrichment
- [Knowledge folders and files](https://docs.atlan.com/llms/governance/knowledge-folders/knowledge-folders-and-files/llms.txt): what knowledge files are and who can upload them
- [Link terms and assets](https://docs.atlan.com/llms/platform/python/link-terms/llms.txt): the term-linking methods these mirror
- [Search assets](https://docs.atlan.com/llms/platform/python/search-assets/llms.txt): find knowledge files and assets by GUID or `qualified_name`

_Last updated: 16 September 2026._

---

> **AI agent?** Install the Atlan Docs MCP for direct access: https://docs.atlan.com/skills/install-docs-mcp.md