Embedding Images in DataHub Markdown Documents Programmatically – DataHub Customer Support Portal

Area: API Issues

Sub-Area: Python SDK & GraphQL — Context Documents / Knowledge Assets

Issue

Users creating DataHub Context Documents programmatically need to embed images within the markdown content. While the DataHub UI provides an image upload button and drag-and-drop functionality for inserting images into documents, it is not immediately obvious how to achieve the same result via the Python SDK or GraphQL API, or where images must be hosted for them to render correctly in the DataHub UI.

You Might Be Asking

How do I embed an image in a DataHub Context Document using the Python SDK?
Where does the image need to be hosted for it to render in a DataHub markdown document?
Can I upload images directly into DataHub and reference them in a document programmatically?
Is there a dedicated upload_image() method in the DataHub Python SDK?

Solution

There are two supported programmatic approaches for embedding images in DataHub Context Documents:

Option 1: Reference an Externally Hosted Image via the Python SDK (Simplest)

The DataHub Python SDK's Document class accepts standard markdown syntax inside the document text. You can embed any image using a standard markdown image tag, provided the image is hosted at a publicly accessible URL.

Host your image at a publicly accessible HTTPS endpoint (e.g., a public CDN, a public cloud storage bucket, or any HTTPS server that serves the image with the correct Content-Type header).

Reference the image using standard markdown syntax inside your document text:

from datahub.sdk.document import Document

doc = Document.create_document(
    title="My Document",
    text=(
        "Here is an embedded image:\n\n"
        "![Alt text for my image](https://<your-image-host>/path/to/image.png)\n\n"
        "Additional document content goes here."
    ),
    # ... other required parameters
)

Ingest the document using the DataHub Python SDK as normal.

Image hosting requirements for Option 1:

The image URL must be reachable from the end user's browser at the time they view the document.
Suitable hosts include public CDNs (e.g., CloudFront, Fastly), public S3 or GCS buckets, or any public HTTPS endpoint.
Images hosted behind a VPN or private network will not render for users outside that network.
There are no restrictions imposed by DataHub on the image host itself.

Option 2: Upload Images to DataHub-Managed Storage via GraphQL (No External Hosting Required)

If you want images to reside within DataHub's own managed storage (rather than an external host), you can use the GraphQL API to upload files. This is a multi-step process:

Step 1 — Request a presigned upload URL from DataHub:

mutation GetPresignedUploadUrl {
  getPresignedUploadUrl(input: {
    fileName: "my-image.png",
    contentType: "image/png",
    scenario: ASSET_DOCUMENTATION
  }) {
    uploadUrl
    fileId
  }
}

Save both the uploadUrl and fileId values returned in the response.

Step 2 — Upload the image binary directly to the presigned URL:

import requests

with open("/path/to/your/image.png", "rb") as image_file:
    response = requests.put(
        "<uploadUrl-from-step-1>",
        data=image_file,
        headers={"Content-Type": "image/png"}
    )
    response.raise_for_status()

Step 3 — Register the uploaded file in DataHub:

mutation CreateDataHubFile {
  createDataHubFile(input: {
    fileId: "<fileId-from-step-1>",
    fileName: "my-image.png",
    contentType: "image/png"
  }) {
    fileId
    downloadUrl
  }
}

The downloadUrl returned here is the DataHub-served URL for your image.

Step 4 — Embed the returned URL in your document content:

from datahub.sdk.document import Document

datahub_image_url = "<downloadUrl-from-step-3>"

doc = Document.create_document(
    title="My Document",
    text=(
        "Here is an image stored in DataHub:\n\n"
        f"![My Image]({datahub_image_url})\n\n"
        "Additional document content goes here."
    ),
    # ... other required parameters
)

Supported image MIME types for Option 2:

image/png
image/jpeg
image/gif
image/webp
image/svg+xml
image/bmp
image/tiff

Comparison of Approaches

Method	Image Location	Programmatic?	Notes
Markdown URL in Python SDK	External host (CDN, public S3, etc.)	✅ Yes	Must be publicly accessible from the user's browser
GraphQL presigned upload flow	DataHub-managed storage	✅ Yes (multi-step)	Full API support; no external hosting required
UI image button (link)	External URL	❌ UI only	Equivalent to Option 1, done through the editor
UI file upload (drag-drop)	DataHub-managed storage	❌ UI only	Equivalent to Option 2, done through the editor

Additional Notes

The DataHub Python SDK does not currently include a dedicated upload_image() method. Image uploads to DataHub-managed storage must go through the GraphQL API directly (Option 2 above). The set_text() and create_document() SDK methods work correctly once you have a final image URL from either approach. The underlying document data model (DocumentContents) stores content as plain text, so images are always referenced via URL within the markdown string rather than stored as binary attachments in the document schema itself. For sensitive or internal images that should not be publicly accessible, Option 2 (DataHub-managed storage via GraphQL) is the recommended approach, as DataHub handles storage permissions and URL generation.