> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FileHandler

> FileHandler — Kinetica TypeScript API

KIFS file access: uploads, downloads, and chunked uploads of large files.Also reachable as `GPUdb.FileHandler`, matching the JavaScript API.

#### Example

```
const files = new FileHandler(gpudb);
await files.upload('/local/path/data.csv', '/kifs_dir/');
const [base64] = await files.download('/kifs_dir/data.csv');
```

<ul>
  <li>Defined in [src/GPUdb.ts:16440](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16440)</li>
</ul>

##### Index

### Constructors

[constructor](#constructor)&#x20;

### Properties

[chunkSize](#chunksize) [gpuDB](#gpudb)&#x20;

### Methods

[download](#download) [download\_and\_save](#download_and_save) [parse\_dir\_destination](#parse_dir_destination) [parse\_flag\_to\_str](#parse_flag_to_str) [parse\_options](#parse_options) [upload](#upload) [upload\_multipart](#upload_multipart) [extract\_filename](#extract_filename)&#x20;

## Constructors

### constructor

<ul>
  <li>
    new FileHandler(gpuDB: [GPUdb](https://docs.kinetica.com/content/api/typescript/classes/GPUdb.md)): FileHandler

    Creates a FileHandler.

    #### Parameters

    <ul>
      <li>
        gpuDB: [GPUdb](https://docs.kinetica.com/content/api/typescript/classes/GPUdb.md)

        Client providing access to the server
      </li>
    </ul>

    #### Returns FileHandler

    <ul>
      <li>Defined in [src/GPUdb.ts:16459](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16459)</li>
    </ul>
  </li>
</ul>

## Properties

### chunkSize

chunkSize: number = ...

Size above which `upload` sends a file as a chunked multipart upload instead of in one request.Matches the JavaScript API's `FileHandler.chunkSize`, including its 60 MB default and its writability -- callers that set their own threshold, as Cloud Workbench does, keep working unchanged.

<ul>
  <li>Defined in [src/GPUdb.ts:16452](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16452)</li>
</ul>

### `Readonly`gpuDB

gpuDB: [GPUdb](https://docs.kinetica.com/content/api/typescript/classes/GPUdb.md)

The client used to reach the server

<ul>
  <li>Defined in [src/GPUdb.ts:16442](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16442)</li>
</ul>

## Methods

### download

<ul>
  <li>
    download(\
    &#x20;filenames: string | string\[],\
    &#x20;options?: Record\<string, string>,\
    &#x20;callback?: [GPUdbCallback](https://docs.kinetica.com/content/api/typescript/types/GPUdbCallback.md),\
    ): Promise\<string\[]>

    Downloads files from KIFS and returns their base64-encoded contents.

    #### Parameters

    <ul>
      <li>
        filenames: string | string\[]

        KIFS path, or an array of paths
      </li>

      <li>
        `Optional`options: Record\<string, string>

        Options for `/download/files`
      </li>

      <li>
        `Optional`callback: [GPUdbCallback](https://docs.kinetica.com/content/api/typescript/types/GPUdbCallback.md)

        Optional callback function
      </li>
    </ul>

    #### Returns Promise\<string\[]>

    Promise resolving to the base64 contents, in request order

    #### Example

    ```
    const [encoded] = await files.download('/kifs_dir/data.csv');
    const text = atob(encoded);
    ```

    <ul>
      <li>Defined in [src/GPUdb.ts:16781](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16781)</li>
    </ul>
  </li>
</ul>

### download\_and\_save

<ul>
  <li>
    download\_and\_save(\
    &#x20;filenames: string | string\[],\
    &#x20;destination: string,\
    &#x20;options?: Record\<string, string>,\
    &#x20;callback?: [GPUdbCallback](https://docs.kinetica.com/content/api/typescript/types/GPUdbCallback.md),\
    ): Promise\<string\[]>

    Downloads files from KIFS and writes them to a local directory.Node.js only -- a browser cannot write to the filesystem. The directory is created if it does not exist.

    #### Parameters

    <ul>
      <li>
        filenames: string | string\[]

        KIFS path, or an array of paths
      </li>

      <li>
        destination: string

        Local directory to write into
      </li>

      <li>
        `Optional`options: Record\<string, string>

        Options for `/download/files`
      </li>

      <li>
        `Optional`callback: [GPUdbCallback](https://docs.kinetica.com/content/api/typescript/types/GPUdbCallback.md)

        Optional callback function
      </li>
    </ul>

    #### Returns Promise\<string\[]>

    Promise resolving to the paths written

    #### Example

    ```
    const written = await files.download_and_save(
        ['/kifs_dir/a.csv', '/kifs_dir/b.csv'], '/local/dir');
    ```

    <ul>
      <li>Defined in [src/GPUdb.ts:16822](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16822)</li>
    </ul>
  </li>
</ul>

### parse\_dir\_destination

<ul>
  <li>
    parse\_dir\_destination(destination?: string | null): string

    Normalises a KIFS directory so it starts and ends with a slash.

    #### Parameters

    <ul>
      <li>
        `Optional`destination: string | null

        Directory path, possibly missing its slashes
      </li>
    </ul>

    #### Returns string

    <ul>
      <li>Defined in [src/GPUdb.ts:16482](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16482)</li>
    </ul>
  </li>
</ul>

### parse\_flag\_to\_str

<ul>
  <li>
    parse\_flag\_to\_str(\
    &#x20;value: string | boolean | null | undefined,\
    &#x20;default\_value: string,\
    ): string

    Coerces a flag to the string form the server expects.

    #### Parameters

    <ul>
      <li>
        value: string | boolean | null | undefined

        Boolean or string flag
      </li>

      <li>
        default\_value: string

        Returned when the value is absent or unusable
      </li>
    </ul>

    #### Returns string

    <ul>
      <li>Defined in [src/GPUdb.ts:16503](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16503)</li>
    </ul>
  </li>
</ul>

### parse\_options

<ul>
  <li>
    parse\_options(\
    &#x20;incoming\_options: Record\<string, string> | null | undefined,\
    &#x20;endpoint: string,\
    ): Record\<string, string>

    Builds the options for a KIFS call, forcing the encoding this handler transfers in. Caller options are preserved, unlike the JavaScript API, which discards them.

    #### Parameters

    <ul>
      <li>
        incoming\_options: Record\<string, string> | null | undefined

        Options supplied by the caller
      </li>

      <li>
        endpoint: string

        'upload' or 'download'
      </li>
    </ul>

    #### Returns Record\<string, string>

    <ul>
      <li>Defined in [src/GPUdb.ts:16524](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16524)</li>
    </ul>
  </li>
</ul>

### upload

<ul>
  <li>
    upload(\
    &#x20;files: string | Blob | (string | Blob)\[],\
    &#x20;destination?: string,\
    &#x20;options?: Record\<string, string>,\
    &#x20;progress\_callback?: [UploadProgressCallback](https://docs.kinetica.com/content/api/typescript/types/UploadProgressCallback.md),\
    &#x20;callback?: [GPUdbCallback](https://docs.kinetica.com/content/api/typescript/types/GPUdbCallback.md),\
    ): Promise\<boolean>

    Uploads files to KIFS.Accepts local paths (Node.js only) or Blob/File objects (any environment), singly or as an array. Unlike the JavaScript API, file contents are read as binary rather than UTF-8, so images, archives and other non-text files survive the round trip.Anything larger than [chunkSize](#chunksize) is sent through [upload\_multipart](#upload_multipart) rather than in a single request, so a big file does not have to be held in one payload -- the same threshold the JavaScript API applied. Everything smaller goes in one batched call.`progress_callback` reports the chunked portion of the work only, as a percentage from 0 to 100. When several files need chunking the percentage spans the whole set rather than restarting per file, so it rises monotonically to 100.

    #### Parameters

    <ul>
      <li>
        files: string | Blob | (string | Blob)\[]

        Local paths, or Blob/File objects
      </li>

      <li>
        `Optional`destination: string

        KIFS directory; defaults to the root
      </li>

      <li>
        `Optional`options: Record\<string, string>

        Options for `/upload/files`
      </li>

      <li>
        `Optional`progress\_callback: [UploadProgressCallback](https://docs.kinetica.com/content/api/typescript/types/UploadProgressCallback.md)

        Percent complete; chunked uploads only
      </li>

      <li>
        `Optional`callback: [GPUdbCallback](https://docs.kinetica.com/content/api/typescript/types/GPUdbCallback.md)

        Optional callback function
      </li>
    </ul>

    #### Returns Promise\<boolean>

    Promise resolving to true when every file was accepted

    #### Example

    ```
    await files.upload(['/local/a.csv', '/local/b.csv'], '/kifs_dir/');
    await files.upload(inputElement.files[0], '/kifs_dir/');   // browser

    // A file over chunkSize is chunked automatically
    await files.upload(bigFile, '/kifs_dir/', {},
        percent => console.log(`${percent.toFixed(1)}%`));
    ```

    <ul>
      <li>Defined in [src/GPUdb.ts:16571](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16571)</li>
    </ul>
  </li>
</ul>

### upload\_multipart

<ul>
  <li>
    upload\_multipart(\
    &#x20;file: string | Blob,\
    &#x20;destination?: string,\
    &#x20;chunk\_size?: number,\
    &#x20;options?: Record\<string, string>,\
    &#x20;progress\_callback?: [UploadProgressCallback](https://docs.kinetica.com/content/api/typescript/types/UploadProgressCallback.md),\
    &#x20;callback?: [GPUdbCallback](https://docs.kinetica.com/content/api/typescript/types/GPUdbCallback.md),\
    ): Promise\<string>

    Uploads one large file to KIFS in chunks.Initiates a multipart upload, sends each chunk in order, then completes it. If any chunk fails the upload is cancelled server-side before the error is rethrown, so no partial upload is left behind.

    #### Parameters

    <ul>
      <li>
        file: string | Blob

        Blob/File to upload, or a local path under Node.js
      </li>

      <li>
        `Optional`destination: string

        KIFS directory; defaults to the root
      </li>

      <li>
        chunk\_size: number = ...

        Bytes per chunk; defaults to 8 MB
      </li>

      <li>
        `Optional`options: Record\<string, string>

        Options for `/upload/files`
      </li>

      <li>
        `Optional`progress\_callback: [UploadProgressCallback](https://docs.kinetica.com/content/api/typescript/types/UploadProgressCallback.md)

        Called with percent complete after each chunk
      </li>

      <li>
        `Optional`callback: [GPUdbCallback](https://docs.kinetica.com/content/api/typescript/types/GPUdbCallback.md)

        Optional callback function
      </li>
    </ul>

    #### Returns Promise\<string>

    Promise resolving to the multipart upload's UUID

    #### Example

    ```
    await files.upload_multipart(bigFile, '/kifs_dir/', 8 * 1024 * 1024, {},
        percent => console.log(`${percent.toFixed(1)}%`));
    ```

    <ul>
      <li>Defined in [src/GPUdb.ts:16680](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16680)</li>
    </ul>
  </li>
</ul>

### `Static`extract\_filename

<ul>
  <li>
    extract\_filename(full\_path: string, sep?: string): string

    Returns the last segment of a path.

    #### Parameters

    <ul>
      <li>
        full\_path: string

        Path to take the name from
      </li>

      <li>
        sep: string = '/'

        Separator to split on
      </li>
    </ul>

    #### Returns string

    <ul>
      <li>Defined in [src/GPUdb.ts:16472](https://github.com/kineticadb/kinetica-api-typescript/blob/master/src/GPUdb.ts#L16472)</li>
    </ul>
  </li>
</ul>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.