You can use request headers to control the following service behaviors:

Some of these behaviors can be controlled with query parameters instead of in headers. See Custom query parameters.

Refresh Result Header

Hybrid Data Pipeline buffers the results of an OData query, allowing clients to page back and forth through the results using the $top and $skip system query parameters. The $top parameter specifies how many results to return in the first response and $skip specifies where to start in the result set to return the next set of results. When the Hybrid Data Pipeline service receives an OData query for which it has a buffered result and the $skip query parameter is either not specified or is set to zero, Hybrid Data Pipeline can page back to the beginning of the buffered result or execute a new query.

By default, Hybrid Data Pipeline treats a query where $skip is missing or set to zero as a request to re-execute the query in the backend data source. You can change default behavior in the data source definition, or in the request with the ddcloud-refresh-result header. The header value overrides the setting in the Refresh Result field of the data source definition.

Name ddcloud-refresh-result
Accepted Values 0, reuse cached results. 1, discard cached results and query the data store again.
Default when not specified 1.The service executes the query anew.

Data Source User Header

The credentials for the backend data source can be stored in the data source definition on the General tab. If they are not, you must supply them in requests using the ddcloud-datasource-user header.

Name ddcloud-datasource-user
Default when not specified The Hybrid Data Pipeline service checks the data source definition for this value.

Data Source Password Header

The credentials for the backend data source can be stored in the data source definition on the General tab. If they are not, you must supply them in requests using the ddcloud-datasource-password header.

Name ddcloud-datasource-password
Default when not specified The Hybrid Data Pipeline service checks the data source definition for this value.

Timezone Header

To correctly process DateTime data types for clients in a different timezone than the data store, use the ddcloud-timezone header.
Name ddcloud-timezone
Accepted Values A Java timezone id string.
Default when not specified The timezone is taken from URL; GMT is used if timezone is not specified as a header or URL parameter

Top Mode

In some cases, the Hybrid Data Pipeline OData service can optimize requests to the backend data store when you use the ddcloud-top-mode to specify how a client will be using the $top system parameter to page through results. A value of 0 indicates that the client will use $top to limit the result set and will rarely request the remaining entities. A value of 1 indicates that the client will often use $top and $skip to page through results.

Hybrid Data Pipeline applies the optimization only to queries that meet the following conditions:

  • Include a value for $top
  • Do not include $skip or include $skip with a value of 0
  • Do not include $expand
  • Do not include $inlinecount=allpages with the inline count mode set to 2, which causes a fetch of all rows

When the conditions are met, Hybrid Data Pipeline will generate only a SELECT statement that includes the data store-specific syntax for limiting the rows returned. If the client queries the same entity collection again but specifies $top and $skip to fetch more entities, the service executes a new query. The results might contain some of the entities already received from the first request.

In the following example, the ddcloud-top-mode is set to 1, directing the Hybrid Data Pipeline service to fetch the complete result set and not to attempt optimization:

ddcloud-top-mode=1
Name ddcloud-top-mode
Accepted Values 0 indicates that the client will use $top to limit the result set and will rarely request the remaining entities

1 indicates that the client will often use $top and $skip to page through results
Default when not specified 0

OData Prefer Header - Max Page Size

The OData 4.0 specification defines a Prefer header, odata.maxpagesize, that can be used to control the page size for server-driven paging. In server-driven paging, the server returns partial results and includes a link the client can use to get the next set of results. Hybrid Data Pipeline supports the OData 2.0 standard, but uses the odata.maxpagesize Prefer header from the OData 4.0 specification to control the page size for server-driven paging.

You can set the page size in the data source definition, on the OData tab, in the Page Size field. The request header value for odata.maxpagesize overrides the value specified in the data source definition. In the following example, the maximum page size is set to 4000, resulting in up to 4000 entities per page.

Prefer: odata.maxpagesize=4000
Name Prefer
Accepted Values odata.maxpagesize=x where x is the maximum number of top-level entities that are returned on a page.
Default when not specified The page size from either the data source or the service default page size.

OIDC Authentication Service Name Header

To connect to an OData 2.0 endpoint using the OIDC authentication service, use the x-datadirect-authService header with bearer as prefix.

Name x-datadirect-authService
Accepted Values An existing OIDC authentication service name string.
Default when not specified OAuth authentication is used if the authentication service header is not specified. Basic authentication is used if the header does not have the bearer prefix.