Uploads a File to an existing Dataset.
The body of the request must contain the binary content of the file and the Content-Type
header must be application/octet-stream
.
By default the file is uploaded to a new transaction on the default branch - master
for most enrollments.
If the file already exists only the most recent version will be visible in the updated view.
See Datasets Core Concepts for details on using branches and transactions.
To upload a file to a specific Branch specify the Branch's identifier as branchId
. A new transaction will
be created and committed on this branch. By default the TransactionType will be UPDATE
, to override this
default specify transactionType
in addition to branchId
.
See createBranch to create a custom branch.
To upload a file on a manually opened transaction specify the Transaction's resource identifier as
transactionRid
. This is useful for uploading multiple files in a single transaction.
See createTransaction to open a transaction.
Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:datasets-write
.
string
The Resource Identifier (RID) of the Dataset on which to upload the File.
string
The File's path within the Dataset.
string
The identifier (name) of the Branch on which to upload the File. Defaults to master
for most enrollments.
string
(enum)The type of the Transaction to create when using branchId. Defaults to UPDATE
.
Enum values: APPEND
, UPDATE
, SNAPSHOT
, DELETE
string
The Resource Identifier (RID) of the open Transaction on which to upload the File.
object
string
The path to a File within Foundry. Examples: my-file.txt
, path/to/my-file.jpg
, dataframe.snappy.parquet
.
string
The Resource Identifier (RID) of a Transaction.
string
string
1curl -X POST \
2 -H "Content-type: application/octet-stream" \
3 -H "Authorization: Bearer $TOKEN" \
4 "https://$HOSTNAME/api/v1/datasets/ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da/files:upload?filePath=q3-data%252fmy-file.csv&branchId=master&transactionType=APPEND&transactionRid=ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4" \
5 --data-binary '@/path/to/file'
1{
2 "path": "q3-data/my-file.csv",
3 "transactionRid": "ri.foundry.main.transaction.bf9515c2-02d4-4703-8f84-c3b3c190254d",
4 "sizeBytes": "74930",
5 "updatedTime": "2022-10-10T16:44:55.192Z"
6}
Error Name | ||
---|---|---|
Invalid | Error Code | INVALID_ARGUMENT |
Status Code | 400 | |
Description | The given parameters are individually valid but cannot be used in the given combination. | |
Parameters | validCombinations, providedParameters | |
Upload | Error Code | PERMISSION_DENIED |
Status Code | 403 | |
Description | The provided token does not have permission to upload the given file to the given dataset and transaction. | |
Parameters | datasetRid, transactionRid, path | |
Open | Error Code | CONFLICT |
Status Code | 409 | |
Description | A transaction is already open on this dataset and branch. A branch of a dataset can only have one open transaction at a time. | |
Parameters | datasetRid, branchId | |
Create | Error Code | PERMISSION_DENIED |
Status Code | 403 | |
Description | The provided token does not have permission to create a transaction on this dataset. | |
Parameters | datasetRid, branchId | |
File | Error Code | NOT_FOUND |
Status Code | 404 | |
Description | The given file path already exists in the dataset and transaction. | |
Parameters | datasetRid, transactionRid, path | |
Invalid | Error Code | INVALID_ARGUMENT |
Status Code | 400 | |
Description | The requested branch name cannot be used. Branch names cannot be empty and must not look like RIDs or UUIDs. | |
Parameters | branchId | |
Branch | Error Code | NOT_FOUND |
Status Code | 404 | |
Description | The requested branch could not be found, or the client token does not have access to it. | |
Parameters | datasetRid, branchId | |
Abort | Error Code | PERMISSION_DENIED |
Status Code | 403 | |
Description | The provided token does not have permission to abort the given transaction on the given dataset. | |
Parameters | datasetRid, transactionRid | |
Dataset | Error Code | NOT_FOUND |
Status Code | 404 | |
Description | The requested dataset could not be found, or the client token does not have access to it. | |
Parameters | datasetRid | |
Transaction | Error Code | NOT_FOUND |
Status Code | 404 | |
Description | The requested transaction could not be found on the dataset, or the client token does not have access to it. | |
Parameters | datasetRid, transactionRid | |
Commit | Error Code | PERMISSION_DENIED |
Status Code | 403 | |
Description | The provided token does not have permission to commit the given transaction on the given dataset. | |
Parameters | datasetRid, transactionRid | |
Transaction | Error Code | INVALID_ARGUMENT |
Status Code | 400 | |
Description | The given transaction is not open. | |
Parameters | datasetRid, transactionRid, transactionStatus |
See Errors for a general overview of errors in the platform.
Upload File • API Reference • Palantir