--- title: "Working with Files" slug: "working-with-files" tags: ["data-integration"] updated: 2026-09-14T17:46:04Z published: 2026-09-14T17:46:04Z canonical: "docs.unqork.io/working-with-files" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # Working with Files The [File component](/unqorkai/docs/file-component) handles file uploads in Unqork. This guide covers storage options, Storage Delivery URLs, how files are represented in submission data, retrieval patterns, and limitations. ## Storage Options Files can be stored in Unqork's cloud storage or in an external file service. The choice is controlled by the File component's **Store Data in Database** setting. ### Storing Files in Unqork When **Store Data in Database** is set to **ON**, files are submitted to Unqork's cloud storage. Unqork handles validation and storage automatically: - File type and extension are validated before upload. Files that do not match the **Set File Formats to Accept** setting are rejected. - Files up to 100 MB are automatically scanned for malware before being stored. Files above 100 MB are not automatically scanned. - Files are stored in the cloud with no practical storage quota. - A Cloud Storage Delivery URL is generated for each file. See [Cloud Storage Delivery URL](/unqorkai/docs/working-with-files#cloud-storage-delivery-url) for details. No additional service configuration is needed—files are uploaded using Unqork's Submission Attachments API. ### Storing Files Externally When **Store Data in Database** is set to **OFF**, Creators must use a [Plug-In component](/unqorkai/docs/plug-in-component) to send the file to an external file service like Google Drive or Dropbox. Consider the following when storing externally: - Creators must set up an API account with the external file service and configure the service in [Services Administration](/unqorkai/docs/services-administration). - Creators are subject to the external file service's pricing and usage quotas. - Creators and the external file service assume all responsibility for virus scanning. - File access permissions depend on the external file service and its configuration. ## Cloud Storage Delivery URL When a file is stored in Unqork cloud storage, a Cloud Storage Delivery URL is generated to provide access to the file. This URL includes a unique signature tied to the logged-in Creator or service account. - Only the user who generates the URL can use it to access the file. - When the file is first uploaded, the returned URL can be saved in a submission. Each time a Creator with access to that submission retrieves the URL, a new signature is generated for that user. - Cloud Storage Delivery URLs expire after 24 hours. ## How Files Are Represented in Submission Data The File component's submission data is an array of objects, where each object represents one file. The structure depends on the **Parse Files on Upload** setting. ### Cloud Storage (Parse Files on Upload: OFF) When **Parse Files on Upload** is **OFF** (the default), the file is stored as a reference in the cloud. The submission data object contains: ```json [  {    "storage": "cloud",    "name": "document.pdf",    "id": "c83ffe8b-6e90-4920-8e37-44a46f21cf42",    "size": 235157,    "type": "application/pdf"  } ] ``` ### Base64 (Parse Files on Upload: ON) When **Parse Files on Upload** is **ON**, the file's data is encoded as a Base64 string before submission. On submitting to Unqork, the Base64 data is replaced with a cloud storage link. > [!WARNING] > Avoid storing files as Base64 unless necessary—for example, to read data from an XLSX or CSV file, or to render a thumbnail preview. Base64 encoding increases the original file size by approximately 33%, which reduces the submission size limit to approximately 18 MB. ## File Compression Unqork automatically compresses images in some cases: - Only PNG and JPG file types can be compressed. - Compression applies regardless of the device or operating system. - Compression is lossy and might reduce image quality. - Compression is not applied when **Parse Files on Upload** is **OFF** (cloud storage mode). ## Sending and Retrieving Files Using a Plug-In Component ### Sending Files Externally When sending files to an external file service using a Plug-In component: - **JSON request body**: **50 MB** — applies to all JSON requests sent through Unqork's server, including requests that send Base64-encoded data to external services. - **Binary file upload (multipart)**: **500 MB per file**. - When sending files to a server-side executed module using a proxy request, the limit is **25 files at 500 MB total**. This applies to the **Execute via Proxy - POST** Unqork service. > Check the external file service's documentation to verify the file size limits accepted by its API. Some external services require batching file uploads into multiple fragments—the Plug-In component does not support batching. ### Retrieving Files Using a Plug-In Component To retrieve a file stored in Unqork cloud storage using a Plug-In component: **As binary**: 1. Use a Plug-In component in a server-side execute module. 2. Set **Data Source URL** to the Cloud Storage Delivery URL (for example, `{{data.fileUrl}}`). 3. Set **Request Type** to . 4. Set **Expect Binary Response** to **ON**. **As Base64**: Use the `resolveBase64` output type, or chain two Plug-In components—a GET request with **Expect Binary Response** set to **ON**, followed by a POST request. > [!NOTE] > Using the `contents` Type to retrieve a file as Base64 has a limit of 10 MB. ## File Component Limitations - **Not a media player**: The File component does not support viewing or playing uploaded files. The only exception is the **Display Thumbnail Images or Icons** setting. - **Not supported inside grids**: The File component cannot be used inside the Advanced Datagrid, Data Grid, Freeform Grid, or Uniform Grid components. - **Request timeout**: Any file-related or API request lasting longer than five minutes will fail. ## Working with File Data in Formulas The following formulas are useful when working with file data in the Calculator or Data Workflow component: | Formula | Description | | --- | --- | | `BASE64(value)` or `TOBASE64(value)` | Encodes a binary value as a Base64 string. | | `FROMBASE64(value)` | Decodes a Base64 string into a binary value. | > [!WARNING] > Never modify file objects stored in submission data. File objects represent Unqork files, and altering them can cause issues with uploads and downloads. --- **Changelog** | Date | Change | | --- | --- | | — | Initial publication. | Malware is software designed to disrupt, damage, or gain access to a computer system. A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity. An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity. Base64 is an encoding and decoding technique used to convert binary data to an ASCII (American Standard for Information Interchange) text format. A string is an object that represents a sequence of characters. Strings typically hold data represented in text form. Rendering is the process of loading components and displaying the final result on the front-end screen. OS (operating system) is the program that manages other application programs on your computer. JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data. The HTTP POST method is used to send data to a server to create or update a resource, typically including the data in the body of the request.