Data Connectors

A Connector stores endpoint, authentication, and connection settings for an external source so that loading, querying, or export workflows can reuse them. Connector configuration is workspace-scoped; credentials should not be copied directly between environments.

Current SDK coverage

In the reviewed moi-python-sdk and moi-go-sdk main branches, the public client covers the Connector file workflow:

  • Upload one or more local files to temporary Connector storage.

  • Preview a local upload or Connector URI.

  • Use staged files to create an import.

  • Obtain a signed download URL for a Connector file.

  • Delete a temporary Connector file.

Neither SDK currently exposes public methods to create, list, read, update, delete, or validate external Connector configurations. They also do not expose Connector methods for browsing a database schema. Create and test the connection under Data Connection > Connectors in AI Studio first, then pass an existing Connector ID or file URI into supported SDK file operations. Do not construct undocumented endpoints.

See the Connector reference for source types and console fields.

Stage and preview a local file

The Python low-level client can upload a file by path:

upload = client.upload_local_file_from_path(
    "/data/orders.csv",
    [{"filename": "orders.csv", "path": "/"}],
)
conn_file_id = upload["conn_file_ids"][0]

preview = client.preview_connector_file(
    {
        "conn_file_id": conn_file_id,
        "isColumnName": True,
        "columnNameRow": 1,
        "rowStart": 2,
        "file_type": 0,
    }
)

Use upload_local_file for an open binary file or upload_local_files for a batch. meta is required and should describe the corresponding filenames and paths.

The Go equivalents are UploadLocalFileFromPath, UploadLocalFile, UploadLocalFiles, and FilePreview:

upload, err := client.UploadLocalFileFromPath(
    ctx,
    "/data/orders.csv",
    []sdk.FileMeta{{Filename: "orders.csv", Path: "/"}},
)
if err != nil {
    return err
}

preview, err := client.FilePreview(ctx, &sdk.FilePreviewRequest{
    ConnFileId: upload.ConnFileIds[0],
})

To preview a file from an existing external Connector, FilePreviewRequest requires connector_id plus either uri or conn_file_id. A local staged file omits connector_id but requires conn_file_id. The SDK validates rowStart in the range 1–1000.

Move from preview to import

Preview returns sample and column information; it does not write to Catalog. Review column names, inferred types, and header placement before building TableConfig:

Upload or select a Connector file
  → preview and verify parsing settings
  → choose a new or existing Table
  → configure column mappings and conflict behavior
  → call upload_connector_file / UploadConnectorFile
  → persist task_id and read task state

See Import and Export Tasks for request and conflict behavior.

Temporary-file lifecycle

download_connector_file / DownloadConnectorFile returns a signed URL. When an import finishes or a staged file is no longer needed, remove it by conn_file_id with delete_connector_file / DeleteConnectorFile.

A Connector file ID is not a Catalog File ID. The former is temporary import preparation; the latter identifies a persistent asset in a Volume. They use different methods.

Security and troubleshooting

  • Never log or commit API keys, database passwords, or object-storage secrets.

  • For a connectivity failure, rerun Test connection in the console before changing task fields.

  • For preview failures, verify the connector_id and uri / conn_file_id combination, file type, header row, and starting row.

  • For import failures, retain the request identifier and task_id, then fetch task details.