Remote Data Sources

Instead of sending all context rows inline, you can reference a remote CSV file via a pre-signed URL. The server fetches the CSV, parses it, and runs the prediction. For datasets up to 2,048 context rows every row is sent to the model. When TCR routing is enabled, datasets exceeding 2,048 context rows are routed through the Tabular Context Registry (TCR): the full context file is uploaded to HANA Data Lake Files and TCR selects a subset at source — no in-memory downsampling occurs. When TCR routing is not enabled, large remote datasets use the direct path and are downsampled in memory. See Large Datasets. Works with any storage that serves CSV over HTTPS — S3, GCS, Azure Blob, BTP Object Store, MinIO, or anywhere else. No credentials are stored on our side; the URL itself carries the access grant.

Overriding the prediction route

By default the server chooses the path automatically based on dataset size: TCR for large datasets when TCR routing is enabled on the server, otherwise the in-memory direct path.

You can override this decision per request with the optional X-Predict-Route header:

Error responses:

• Requesting tcr while TCR routing is disabled returns 400 with code ERR_TCR_ROUTE_DISABLED.
• Any value other than tcr or direct returns 400 with code ERR_PRED_ROUTE_INVALID.

The header applies to both inline and remote data source requests.

Request Format

{
  "dataSource": {
    "type": "url",
    "url": "https://my-bucket.s3.amazonaws.com/sales_data.csv"
  },
  "index_column": "CUSTOMER_ID",
  "explanations": {
    "top_column_scores": 4,
    "top_relevant_context_rows": 3
  }
}

Request Parameters

• dataSource (required): Remote data source configuration.
  • dataSource.type (required): Provider type. Currently only "url" is supported.
  • dataSource.url (required): HTTPS URL to a CSV file. Must start with https://. Maximum 8,192 characters.
• index_column (optional): Same as inline mode.
• sampler_options (optional): Same as inline mode.
• explanations (optional): Same as inline mode.

Note: Query rows (rows) are not supported in remote data source mode. The CSV file must contain both context rows and query rows (with [PREDICT] placeholders).

Response Format

{
  "prediction": {
    "id": "51fe6c9d-f97f-428d-a59c-093046eb2bd6",
    "status": {
      "code": 0,
      "message": "ok"
    },
    "metadata": {
      "num_columns": 3,
      "num_predictions": 1,
      "num_query_rows": 1,
      "num_rows": 2049
    },
    "predictions": [
      {
        "CUSTOMER_ID": "C-1042",
        "DAYS_LATE": [
          {
            "prediction": 14.5,
            "confidence": null,
            "confidence_interval": [0, 42]
          }
        ]
      }
    ],
    "explanations": null
  },
  "delay": 520.1,
  "source": {
    "type": "url",
    "url": "https://my-bucket.s3.amazonaws.com/sales_data.csv"
  },
  "contextRows": {
    "fetched": 50000,
    "sampled": 2048,
    "strategy": "random",
    "downsampled": true
  }
}

Additional Response Fields

Fields specific to Remote Data Source mode:

• source (object):
  • source.type (string): Echoes the request's dataSource.type.
  • source.url (string): Echoes the request's dataSource.url.
• contextRows (object): Context row counts. Present when a remote data source is used.
  • contextRows.fetched (integer): Number of context rows fetched from the remote URL.
  • contextRows.sampled (integer): Number of context rows actually sent to the model.
  • contextRows.strategy (string): Sampling strategy used.
  • contextRows.downsampled (boolean): Whether downsampling occurred.
• samplingMetadata: Present on the direct path (datasets at or below 2,048 context rows, or when the request uses the direct path because direct is forced or TCR routing is not enabled on the server). For remote datasets routed through TCR, samplingMetadata is omitted and contextRows carries the equivalent information. See Response Format for the samplingMetadata field description.

Limits

For env variable names, see Limits & Quotas.