Volumes, Folders, and Files¶

A Volume stores unstructured assets such as documents, images, audio, and video. Folders organize a hierarchy inside a Volume, while Files carry metadata and expose download or preview access:

Database → Volume → nested Folder → File

Python exposes snake_case methods on RawClient; Go exposes PascalCase methods on RawClient. Examples below reuse the Python client created in Catalogs, Databases, and Tables.

Create a Volume and Folder¶

volume = client.create_volume(
    {
        "database_id": 201,
        "name": "source_documents",
        "description": "Documents awaiting processing",
    }
)
folder = client.create_folder(
    {"name": "2026", "volume_id": "vol-1", "parent_id": ""}
)

Replace the sample IDs with values returned by the service. For a nested Folder, pass the parent Folder ID as parent_id. The corresponding Go methods are CreateVolume and CreateFolder.

Use get_volume_full_path / GetVolumeFullPath to resolve a Volume or Folder ID to its complete location before a destructive operation or bulk write.

Choose the correct upload path¶

The SDK’s file methods serve distinct workflows:

Goal	Python method	Result
Import local unstructured files into a Volume	`SDKClient.import_local_file_to_volume`, `import_local_files_to_volume`	Uploads files and returns the import result
Stage local files for a subsequent table import	`RawClient.upload_local_file*`	Returns `conn_file_ids` for preview and table import
Call the Catalog file-metadata API directly	`create_file`, `upload_file`	Low-level operation; the caller must provide the exact server metadata

Application code should normally prefer the high-level SDKClient Volume helper:

from moi import SDKClient

sdk = SDKClient(client)
result = sdk.import_local_file_to_volume(
    "/data/handbook.docx",
    "vol-1",
    {"filename": "handbook.docx", "path": "handbook.docx"},
    {"by": ["name", "md5"], "strategy": "skip"},
)

For a batch, call import_local_files_to_volume(paths, volume_id, metadata, dedup). The paths and metadata lists must align. Use only deduplication fields and strategies supported by the SDK.

The Go SDK uses UploadConnectorFile for advanced uploads with filtering, deduplication, or Table configuration, and UploadFile for the simple Catalog upload API. UploadConnectorFile is intentionally different from UploadFile in file.go.

List and find Files¶

list_files / ListFiles supports pagination and filters. The Python high-level client also searches by name within a Volume:

page = client.list_files(
    {"keyword": "", "common_condition": {"page": 1, "page_size": 20}}
)
matches = sdk.find_files_by_name("handbook", "vol-1")

Use pagination metadata returned by the service to stop iteration; do not assume that one page contains the complete Volume.

Download and preview¶

get_file_download_link / GetFileDownloadLink returns a temporary signed download URL.
get_file_preview_link / GetFilePreviewLink returns a preview URL for a browser or application.
get_file_preview_stream / GetFilePreviewStream returns a streaming preview URL.
get_file / GetFile reads metadata such as name, size, and type.

Preview support depends on the file type and backend processing state. Signed URLs can expire; obtain a new URL when needed instead of persisting one for long-term use.

Update, clean, and delete¶

update_volume, update_folder, and update_file change the metadata allowed for each resource. Delete operations have different blast radii:

Operation	Effect
`delete_file`	Permanently removes one File
`clean_folder`	Removes all Files and child Folders but retains the Folder
`delete_folder`	Removes the complete Folder tree
`delete_volume`	Removes the Volume and all of its Folders and Files

Before deletion, call get_folder_ref_list or get_volume_ref_list, and verify the target ID and full path. Use delete_file_ref only to delete a reference record; it is not a substitute for deleting the actual File by ID.