File Type

TailorDB File Type enables developers to attach files to records in their data model, providing seamless file management capabilities integrated with GraphQL queries and HTTP operations. This feature eliminates the need for separate file storage solutions by providing:

  • Integrated file storage with TailorDB records
  • Attachment file management (size, checksum, content type, timestamps)
  • Permission-based access control aligned with record-level permissions
  • GraphQL query integration for file metadata filtering

Basic Workflow

  1. Define file attachments in your schema (CUE or Terraform)
  2. Create records with file attachment fields
  3. Upload files via HTTP PUT to auto-generated URLs
  4. Query file info through GraphQL
  5. Download files via HTTP GET
  6. Delete files via HTTP DELETE

Schema Definition

Files are defined in the Files section (not Fields) of your type definition. Each file type field in a record has a reserved URL endpoint that serves as both the upload and download location for that specific field. This URL is automatically generated when the record is created and remains constant throughout the record's lifecycle.

<span><span style="color: var(--shiki-color-text)">Starship: tailordb.#Type </span><span style="color: var(--shiki-token-keyword)">&amp;</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">    Name: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Starship</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">    Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">A transport craft with file attachments</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">    Fields: {</span></span>
<span><span style="color: var(--shiki-color-text)">        name: {</span></span>
<span><span style="color: var(--shiki-color-text)">            Type: tailordb.#TypeString</span></span>
<span><span style="color: var(--shiki-color-text)">            Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Name of the starship</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">        }</span></span>
<span><span style="color: var(--shiki-color-text)">    }</span></span>
<span><span style="color: var(--shiki-color-text)">    Files: {</span></span>
<span><span style="color: var(--shiki-color-text)">        blueprint: tailordb.#Attachment </span><span style="color: var(--shiki-token-keyword)">&amp;</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">            Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Technical blueprint file</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">        }</span></span>
<span><span style="color: var(--shiki-color-text)">        thumbnail: tailordb.#Attachment </span><span style="color: var(--shiki-token-keyword)">&amp;</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">            Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Thumbnail image</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">        }</span></span>
<span><span style="color: var(--shiki-color-text)">    }</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>
<span><span style="color: var(--shiki-token-function)">resource</span><span style="color: var(--shiki-color-text)"> &quot;tailor_tailordb_type&quot; &quot;starship&quot; {</span></span>
<span><span style="color: var(--shiki-color-text)">  workspace_id </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> tailor_workspace.starwars.id</span></span>
<span><span style="color: var(--shiki-color-text)">  namespace    </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> tailor_tailordb.galaxy.namespace</span></span>
<span><span style="color: var(--shiki-color-text)">  name         </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Starship&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">  description  </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;A transport craft with file attachments&quot;</span></span>
<span></span>
<span><span style="color: var(--shiki-color-text)">  fields </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">    name </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">      type        </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;string&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">      description </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Name of the starship&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">    }</span></span>
<span><span style="color: var(--shiki-color-text)">  }</span></span>
<span></span>
<span><span style="color: var(--shiki-color-text)">  files </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">    blueprint </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">      description </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Technical blueprint file&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">    }</span></span>
<span><span style="color: var(--shiki-color-text)">    thumbnail </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">      description </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Thumbnail image&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">    }</span></span>
<span><span style="color: var(--shiki-color-text)">  }</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>

GraphQL Operations

Querying File Metadata

When you query a record with file attachments, each file field returns metadata about the attached file:

<span><span style="color: var(--shiki-token-keyword)">query</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-function)">show</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">  starship(id:</span><span style="color: var(--shiki-token-comment)">&quot;72f157d3-9f3f-40f8-9517-7627909d3580&quot;</span><span style="color: var(--shiki-color-text)">){</span></span>
<span><span style="color: var(--shiki-color-text)">    name</span></span>
<span><span style="color: var(--shiki-color-text)">    blueprint{ url size contentType lastUploadedAt sha256sum }</span></span>
<span><span style="color: var(--shiki-color-text)">    thumbnail{ url size contentType lastUploadedAt sha256sum }</span></span>
<span><span style="color: var(--shiki-color-text)">  }</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>
<span><span style="color: var(--shiki-color-text)">{</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-keyword)">&quot;data&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-keyword)">&quot;starship&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">      </span><span style="color: var(--shiki-token-keyword)">&quot;name&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Millennium Falcon&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">      </span><span style="color: var(--shiki-token-keyword)">&quot;blueprint&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;url&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;https://app.tailor.tech/files/tailordb/galaxy/Starship/blueprint/72f157d3-9f3f-40f8-9517-7627909d3580&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;size&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">6542</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;contentType&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;image/png&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;lastUploadedAt&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;2025-08-26T10:09:13.452171+09:00&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;sha256sum&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;a6034bb72c22843b3b06e59a8a9bf85b58fec62d71e69fe9c2ab61924fc25a98&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">      }</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">      </span><span style="color: var(--shiki-token-keyword)">&quot;thumbnail&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;url&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;https://app.tailor.tech/files/tailordb/galaxy/Starship/thumbnail/72f157d3-9f3f-40f8-9517-7627909d3580&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;size&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">null</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;contentType&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">null</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;lastUploadedAt&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">null</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;sha256sum&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">null</span></span>
<span><span style="color: var(--shiki-color-text)">      }</span></span>
<span><span style="color: var(--shiki-color-text)">    }</span></span>
<span><span style="color: var(--shiki-color-text)">  }</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>

File Metadata Properties

PropertyTypeDescription
urlString!Upload/download endpoint URL
sizeIntFile size in bytes (null before upload)
sha256sumStringSHA256 checksum of file content
lastUploadedAtDateTimeTimestamp of last upload
contentTypeStringMIME type of the file

Filtering by File Existence

You can filter records based on whether files exist:

<span><span style="color: var(--shiki-token-keyword)">query</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-function)">getStarshipsWithFiles</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">  starships(query: {</span></span>
<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-string)">blueprint</span><span style="color: var(--shiki-color-text)">: { </span><span style="color: var(--shiki-token-string)">exists</span><span style="color: var(--shiki-color-text)">: </span><span style="color: var(--shiki-token-constant)">true</span><span style="color: var(--shiki-color-text)"> }</span></span>
<span><span style="color: var(--shiki-color-text)">  }) {</span></span>
<span><span style="color: var(--shiki-color-text)">    edges {</span></span>
<span><span style="color: var(--shiki-color-text)">      node {</span></span>
<span><span style="color: var(--shiki-color-text)">        id</span></span>
<span><span style="color: var(--shiki-color-text)">        name</span></span>
<span><span style="color: var(--shiki-color-text)">        blueprint {</span></span>
<span><span style="color: var(--shiki-color-text)">          url</span></span>
<span><span style="color: var(--shiki-color-text)">          size</span></span>
<span><span style="color: var(--shiki-color-text)">          contentType</span></span>
<span><span style="color: var(--shiki-color-text)">          sha256sum</span></span>
<span><span style="color: var(--shiki-color-text)">          lastUploadedAt</span></span>
<span><span style="color: var(--shiki-color-text)">        }</span></span>
<span><span style="color: var(--shiki-color-text)">      }</span></span>
<span><span style="color: var(--shiki-color-text)">    }</span></span>
<span><span style="color: var(--shiki-color-text)">  }</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>

HTTP File Operations

Upload File

Use HTTP PUT to upload a file to the auto-generated URL endpoint:

<span><span style="color: var(--shiki-token-function)">curl</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">-X</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">PUT</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string-expression)">&quot;https://app.tailor.tech/files/tailordb/galaxy/Starship/cd7b898e-3779-4e3f-b484-607e92df1ebc/blueprint&quot;</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string)">-H</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Authorization: Bearer YOUR_TOKEN&quot;</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string)">-H</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Content-Type: application/pdf&quot;</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string)">--data-binary</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">@blueprint.pdf</span></span>
<span></span>

Download File

Use HTTP GET to download a file from the endpoint:

<span><span style="color: var(--shiki-token-function)">curl</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">-X</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">GET</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string-expression)">&quot;https://app.tailor.tech/files/tailordb/galaxy/Starship/cd7b898e-3779-4e3f-b484-607e92df1ebc/blueprint&quot;</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string)">-H</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Authorization: Bearer YOUR_TOKEN&quot;</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string)">-o</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">downloaded_blueprint.pdf</span></span>
<span></span>

Delete File

Use HTTP DELETE to remove a file:

<span><span style="color: var(--shiki-token-function)">curl</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">-X</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">DELETE</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string-expression)">&quot;https://app.tailor.tech/files/tailordb/galaxy/Starship/cd7b898e-3779-4e3f-b484-607e92df1ebc/blueprint&quot;</span><span style="color: var(--shiki-color-text)"> \</span></span>
<span><span style="color: var(--shiki-color-text)">  </span><span style="color: var(--shiki-token-string)">-H</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Authorization: Bearer YOUR_TOKEN&quot;</span></span>
<span></span>

Limitations and Notes

  • You can specify up to 10 file types in the Files section of your schema
  • The maximum file size allowed for upload is 100 MB
  • If you upload a file to the same endpoint, the existing file will be overwritten
  • File access permissions are aligned with record-level permissions
  • Each file attachment has a unique, persistent URL that remains constant throughout the record's lifecycle
  • When a record is deleted, all attached files are automatically deleted as well

Related Documentation