Input sources

The input source defines where your index task reads data for Apache Druid native batch ingestion. Only the native parallel task and simple task support the input source.

For general information on native batch indexing and parallel task indexing, see Native batch ingestion.

S3 input source

Input sources - 图1info

You need to include the druid-s3-extensions as an extension to use the S3 input source.

The S3 input source reads objects directly from S3. You can specify either:

  • a list of S3 URI strings
  • a list of S3 location prefixes that attempts to list the contents and ingest all objects contained within the locations.

The S3 input source is splittable. Therefore, you can use it with the Parallel task. Each worker task of index_parallel reads one or multiple objects.

Sample specs:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "s3",
  6. "objectGlob": "**.json",
  7. "uris": ["s3://foo/bar/file.json", "s3://bar/foo/file2.json"]
  8. },
  9. "inputFormat": {
  10. "type": "json"
  11. },
  12. ...
  13. },
  14. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "s3",
  6. "objectGlob": "**.parquet",
  7. "prefixes": ["s3://foo/bar/", "s3://bar/foo/"]
  8. },
  9. "inputFormat": {
  10. "type": "json"
  11. },
  12. ...
  13. },
  14. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "s3",
  6. "objectGlob": "**.json",
  7. "objects": [
  8. { "bucket": "foo", "path": "bar/file1.json"},
  9. { "bucket": "bar", "path": "foo/file2.json"}
  10. ]
  11. },
  12. "inputFormat": {
  13. "type": "json"
  14. },
  15. ...
  16. },
  17. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "s3",
  6. "objectGlob": "**.json",
  7. "uris": ["s3://foo/bar/file.json", "s3://bar/foo/file2.json"],
  8. "properties": {
  9. "accessKeyId": "KLJ78979SDFdS2",
  10. "secretAccessKey": "KLS89s98sKJHKJKJH8721lljkd"
  11. }
  12. },
  13. "inputFormat": {
  14. "type": "json"
  15. },
  16. ...
  17. },
  18. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "s3",
  6. "objectGlob": "**.json",
  7. "uris": ["s3://foo/bar/file.json", "s3://bar/foo/file2.json"],
  8. "properties": {
  9. "accessKeyId": "KLJ78979SDFdS2",
  10. "secretAccessKey": "KLS89s98sKJHKJKJH8721lljkd",
  11. "assumeRoleArn": "arn:aws:iam::2981002874992:role/role-s3"
  12. }
  13. },
  14. "inputFormat": {
  15. "type": "json"
  16. },
  17. ...
  18. },
  19. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "s3",
  6. "uris": ["s3://foo/bar/file.json", "s3://bar/foo/file2.json"],
  7. "endpointConfig": {
  8. "url" : "s3-store.aws.com",
  9. "signingRegion" : "us-west-2"
  10. },
  11. "clientConfig": {
  12. "protocol" : "http",
  13. "disableChunkedEncoding" : true,
  14. "enablePathStyleAccess" : true,
  15. "forceGlobalBucketAccessEnabled" : false
  16. },
  17. "proxyConfig": {
  18. "host" : "proxy-s3.aws.com",
  19. "port" : 8888,
  20. "username" : "admin",
  21. "password" : "admin"
  22. },
  23. "properties": {
  24. "accessKeyId": "KLJ78979SDFdS2",
  25. "secretAccessKey": "KLS89s98sKJHKJKJH8721lljkd",
  26. "assumeRoleArn": "arn:aws:iam::2981002874992:role/role-s3"
  27. }
  28. },
  29. "inputFormat": {
  30. "type": "json"
  31. },
  32. ...
  33. },
  34. ...
PropertyDescriptionDefaultRequired
typeSet the value to s3.Noneyes
urisJSON array of URIs where S3 objects to be ingested are located.Noneuris or prefixes or objects must be set
prefixesJSON array of URI prefixes for the locations of S3 objects to be ingested. Empty objects starting with one of the given prefixes will be skipped.Noneuris or prefixes or objects must be set
objectsJSON array of S3 Objects to be ingested.Noneuris or prefixes or objects must be set
objectGlobA glob for the object part of the S3 URI. In the URI s3://foo/bar/file.json, the glob is applied to bar/file.json.

The glob must match the entire object part, not just the filename. For example, the glob .json does not match s3://foo/bar/file.json, because the object part is bar/file.json, and the does not match the slash. To match all objects ending in .json, use **.json instead.

For more information, refer to the documentation for FileSystem#getPathMatcher.
Noneno
systemFieldsJSON array of system fields to return as part of input rows. Possible values: file_uri (S3 URI starting with s3://), file_bucket (S3 bucket), and __file_path (S3 object key).Noneno
endpointConfigConfig for overriding the default S3 endpoint and signing region. This would allow ingesting data from a different S3 store. Please see s3 config for more information.NoneNo (defaults will be used if not given)
clientConfigS3 client properties for the overridden s3 endpoint. This is used in conjunction with endPointConfig. Please see s3 config for more information.NoneNo (defaults will be used if not given)
proxyConfigProperties for specifying proxy information for the overridden s3 endpoint. This is used in conjunction with clientConfig. Please see s3 config for more information.NoneNo (defaults will be used if not given)
propertiesProperties Object for overriding the default S3 configuration. See below for more information.NoneNo (defaults will be used if not given)

Note that the S3 input source will skip all empty objects only when prefixes is specified.

S3 Object:

PropertyDescriptionDefaultRequired
bucketName of the S3 bucketNoneyes
pathThe path where data is located.Noneyes

Properties Object:

PropertyDescriptionDefaultRequired
accessKeyIdThe Password Provider or plain text string of this S3 input source access keyNoneyes if secretAccessKey is given
secretAccessKeyThe Password Provider or plain text string of this S3 input source secret keyNoneyes if accessKeyId is given
assumeRoleArnAWS ARN of the role to assume see. assumeRoleArn can be used either with the ingestion spec AWS credentials or with the default S3 credentialsNoneno
assumeRoleExternalIdA unique identifier that might be required when you assume a role in another account seeNoneno

Input sources - 图2info

Note: If accessKeyId and secretAccessKey are not given, the default S3 credentials provider chain is used.

Google Cloud Storage input source

Input sources - 图3info

You need to include the druid-google-extensions as an extension to use the Google Cloud Storage input source.

The Google Cloud Storage input source is to support reading objects directly from Google Cloud Storage. Objects can be specified as list of Google Cloud Storage URI strings. The Google Cloud Storage input source is splittable and can be used by the Parallel task, where each worker task of index_parallel will read one or multiple objects.

Sample specs:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "google",
  6. "objectGlob": "**.json",
  7. "uris": ["gs://foo/bar/file.json", "gs://bar/foo/file2.json"]
  8. },
  9. "inputFormat": {
  10. "type": "json"
  11. },
  12. ...
  13. },
  14. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "google",
  6. "objectGlob": "**.parquet",
  7. "prefixes": ["gs://foo/bar/", "gs://bar/foo/"]
  8. },
  9. "inputFormat": {
  10. "type": "json"
  11. },
  12. ...
  13. },
  14. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "google",
  6. "objectGlob": "**.json",
  7. "objects": [
  8. { "bucket": "foo", "path": "bar/file1.json"},
  9. { "bucket": "bar", "path": "foo/file2.json"}
  10. ]
  11. },
  12. "inputFormat": {
  13. "type": "json"
  14. },
  15. ...
  16. },
  17. ...
PropertyDescriptionDefaultRequired
typeSet the value to google.Noneyes
urisJSON array of URIs where Google Cloud Storage objects to be ingested are located.Noneuris or prefixes or objects must be set
prefixesJSON array of URI prefixes for the locations of Google Cloud Storage objects to be ingested. Empty objects starting with one of the given prefixes will be skipped.Noneuris or prefixes or objects must be set
objectsJSON array of Google Cloud Storage objects to be ingested.Noneuris or prefixes or objects must be set
objectGlobA glob for the object part of the S3 URI. In the URI s3://foo/bar/file.json, the glob is applied to bar/file.json.

The glob must match the entire object part, not just the filename. For example, the glob .json does not match s3://foo/bar/file.json, because the object part is bar/file.json, and the does not match the slash. To match all objects ending in .json, use **.json instead.

For more information, refer to the documentation for FileSystem#getPathMatcher.
Noneno

Note that the Google Cloud Storage input source will skip all empty objects only when prefixes is specified.

Google Cloud Storage object:

PropertyDescriptionDefaultRequired
bucketName of the Google Cloud Storage bucketNoneyes
pathThe path where data is located.Noneyes
systemFieldsJSON array of system fields to return as part of input rows. Possible values: file_uri (Google Cloud Storage URI starting with gs://), file_bucket (GCS bucket), and __file_path (GCS key).Noneno

Azure input source

Input sources - 图4info

You need to include the druid-azure-extensions as an extension to use the Azure input source.

The Azure input source (that uses the type azureStorage) reads objects directly from Azure Blob store or Azure Data Lake sources. You can specify objects as a list of file URI strings or prefixes. You can split the Azure input source for use with Parallel task indexing and each worker task reads one chunk of the split data.

The azureStorage input source is a new schema for Azure input sources that allows you to specify which storage account files should be ingested from. We recommend that you update any specs that use the old azure schema to use the new azureStorage schema. The new schema provides more functionality than the older azure schema.

Sample specs:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "azureStorage",
  6. "objectGlob": "**.json",
  7. "uris": ["azureStorage://storageAccount/container/prefix1/file.json", "azureStorage://storageAccount/container/prefix2/file2.json"]
  8. },
  9. "inputFormat": {
  10. "type": "json"
  11. },
  12. ...
  13. },
  14. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "azureStorage",
  6. "objectGlob": "**.parquet",
  7. "prefixes": ["azureStorage://storageAccount/container/prefix1/", "azureStorage://storageAccount/container/prefix2/"]
  8. },
  9. "inputFormat": {
  10. "type": "json"
  11. },
  12. ...
  13. },
  14. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "azureStorage",
  6. "objectGlob": "**.json",
  7. "objects": [
  8. { "bucket": "storageAccount", "path": "container/prefix1/file1.json"},
  9. { "bucket": "storageAccount", "path": "container/prefix2/file2.json"}
  10. ],
  11. "properties": {
  12. "sharedAccessStorageToken": "?sv=...<storage token secret>...",
  13. }
  14. },
  15. "inputFormat": {
  16. "type": "json"
  17. },
  18. ...
  19. },
  20. ...
PropertyDescriptionDefaultRequired
typeSet the value to azureStorage.Noneyes
urisJSON array of URIs where the Azure objects to be ingested are located. Use this format: azureStorage://STORAGE_ACCOUNT/CONTAINER/PATH_TO_FILENoneOne of the following must be set:uris, prefixes, or objects.
prefixesJSON array of URI prefixes for the locations of Azure objects to ingest. Use this formatazureStorage://STORAGE_ACCOUNT/CONTAINER/PREFIX. Empty objects starting with any of the given prefixes are skipped.NoneOne of the following must be set:uris, prefixes, or objects.
objectsJSON array of Azure objects to ingest.NoneOne of the following must be set:uris, prefixes, or objects.
objectGlobA glob for the object part of the Azure URI. In the URI azureStorage://foo/bar/file.json, the glob is applied to bar/file.json.

The glob must match the entire object part, not just the filename. For example, the glob .json does not match azureStorage://foo/bar/file.json because the object part is bar/file.json, and the does not match the slash. To match all objects ending in .json, use **.json instead.

For more information, refer to the documentation for FileSystem#getPathMatcher.
Noneno
systemFieldsJSON array of system fields to return as part of input rows. Possible values: file_uri (Azure blob URI starting with azureStorage://), file_bucket (Azure bucket), and __file_path (Azure object path).Noneno
propertiesProperties object for overriding the default Azure configuration. See below for more information.NoneNo (defaults will be used if not given)

Note that the Azure input source skips all empty objects only when prefixes is specified.

The objects property can one of the following:

PropertyDescriptionDefaultRequired
bucketName of the Azure Blob Storage or Azure Data Lake storage accountNoneyes
pathThe container and path where data is located.Noneyes

The properties property can be one of the following:

  • sharedAccessStorageToken
  • key
  • appRegistrationClientId, appRegistrationClientSecret, and tenantId
  • empty
PropertyDescriptionDefaultRequired
sharedAccessStorageTokenThe plain text string of this Azure Blob Storage Shared Access TokenNoneNo
keyThe root key of Azure Blob Storage AccountNoneno
appRegistrationClientIdThe client ID of the Azure App registration to authenticate asNoneNo
appRegistrationClientSecretThe client secret of the Azure App registration to authenticate asNoneYes if appRegistrationClientId is provided
tenantIdThe tenant ID of the Azure App registration to authenticate asNoneYes if appRegistrationClientId is provided

azure input source

The Azure input source that uses the type azure is an older version of the Azure input type and is not recommended. It doesn’t support specifying which storage account to ingest from. We recommend using the azureStorage input source schema instead since it provides more functionality.

Sample specs:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "azure",
  6. "objectGlob": "**.json",
  7. "uris": ["azure://container/prefix1/file.json", "azure://container/prefix2/file2.json"]
  8. },
  9. "inputFormat": {
  10. "type": "json"
  11. },
  12. ...
  13. },
  14. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "azure",
  6. "objectGlob": "**.parquet",
  7. "prefixes": ["azure://container/prefix1/", "azure://container/prefix2/"]
  8. },
  9. "inputFormat": {
  10. "type": "json"
  11. },
  12. ...
  13. },
  14. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "azure",
  6. "objectGlob": "**.json",
  7. "objects": [
  8. { "bucket": "container", "path": "prefix1/file1.json"},
  9. { "bucket": "container", "path": "prefix2/file2.json"}
  10. ]
  11. },
  12. "inputFormat": {
  13. "type": "json"
  14. },
  15. ...
  16. },
  17. ...
PropertyDescriptionDefaultRequired
typeSet the value to azure.Noneyes
urisJSON array of URIs where the Azure objects to be ingested are located, in the form azure://<container>/<path-to-file>Noneuris or prefixes or objects must be set
prefixesJSON array of URI prefixes for the locations of Azure objects to ingest, in the form azure://<container>/<prefix>. Empty objects starting with one of the given prefixes are skipped.Noneuris or prefixes or objects must be set
objectsJSON array of Azure objects to ingest.Noneuris or prefixes or objects must be set
objectGlobA glob for the object part of the Azure URI. In the URI azure://foo/bar/file.json, the glob is applied to bar/file.json.

The glob must match the entire object part, not just the filename. For example, the glob .json does not match azure://foo/bar/file.json, because the object part is bar/file.json, and the does not match the slash. To match all objects ending in .json, use **.json instead.

For more information, refer to the documentation for FileSystem#getPathMatcher.
Noneno
systemFieldsJSON array of system fields to return as part of input rows. Possible values: file_uri (Azure blob URI starting with azure://), file_bucket (Azure bucket), and __file_path (Azure object path).Noneno

Note that the Azure input source skips all empty objects only when prefixes is specified.

The objects property is:

PropertyDescriptionDefaultRequired
bucketName of the Azure Blob Storage or Azure Data Lake containerNoneyes
pathThe path where data is located.Noneyes

HDFS input source

Input sources - 图5info

You need to include the druid-hdfs-storage as an extension to use the HDFS input source.

The HDFS input source is to support reading files directly from HDFS storage. File paths can be specified as an HDFS URI string or a list of HDFS URI strings. The HDFS input source is splittable and can be used by the Parallel task, where each worker task of index_parallel will read one or multiple files.

Sample specs:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "hdfs",
  6. "paths": "hdfs://namenode_host/foo/bar/", "hdfs://namenode_host/bar/foo"
  7. },
  8. "inputFormat": {
  9. "type": "json"
  10. },
  11. ...
  12. },
  13. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "hdfs",
  6. "paths": "hdfs://namenode_host/foo/bar/", "hdfs://namenode_host/bar/foo"
  7. },
  8. "inputFormat": {
  9. "type": "json"
  10. },
  11. ...
  12. },
  13. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "hdfs",
  6. "paths": "hdfs://namenode_host/foo/bar/file.json", "hdfs://namenode_host/bar/foo/file2.json"
  7. },
  8. "inputFormat": {
  9. "type": "json"
  10. },
  11. ...
  12. },
  13. ...
  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "hdfs",
  6. "paths": ["hdfs://namenode_host/foo/bar/file.json", "hdfs://namenode_host/bar/foo/file2.json"]
  7. },
  8. "inputFormat": {
  9. "type": "json"
  10. },
  11. ...
  12. },
  13. ...
PropertyDescriptionDefaultRequired
typeSet the value to hdfs.Noneyes
pathsHDFS paths. Can be either a JSON array or comma-separated string of paths. Wildcards like * are supported in these paths. Empty files located under one of the given paths will be skipped.Noneyes
systemFieldsJSON array of system fields to return as part of input rows. Possible values: file_uri (URI) and file_path (path component of URI).Noneno

You can also ingest from other storage using the HDFS input source if the HDFS client supports that storage. However, if you want to ingest from cloud storage, consider using the service-specific input source for your data storage. If you want to use a non-hdfs protocol with the HDFS input source, include the protocol in druid.ingestion.hdfs.allowedProtocols. See HDFS input source security configuration for more details.

HTTP input source

The HTTP input source is to support reading files directly from remote sites via HTTP.

Input sources - 图6info

Security notes: Ingestion tasks run under the operating system account that runs the Druid processes, for example the Indexer, Middle Manager, and Peon. This means any user who can submit an ingestion task can specify an input source referring to any location that the Druid process can access. For example, using http input source, users may have access to internal network servers.

The http input source is not limited to the HTTP or HTTPS protocols. It uses the Java URI class that supports HTTP, HTTPS, FTP, file, and jar protocols by default.

For more information about security best practices, see Security overview.

The HTTP input source is splittable and can be used by the Parallel task, where each worker task of index_parallel will read only one file. This input source does not support Split Hint Spec.

Sample specs:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "http",
  6. "uris": ["http://example.com/uri1", "http://example2.com/uri2"]
  7. },
  8. "inputFormat": {
  9. "type": "json"
  10. },
  11. ...
  12. },
  13. ...

Example with authentication fields using the DefaultPassword provider (this requires the password to be in the ingestion spec):

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "http",
  6. "uris": ["http://example.com/uri1", "http://example2.com/uri2"],
  7. "httpAuthenticationUsername": "username",
  8. "httpAuthenticationPassword": "password123"
  9. },
  10. "inputFormat": {
  11. "type": "json"
  12. },
  13. ...
  14. },
  15. ...

You can also use the other existing Druid PasswordProviders. Here is an example using the EnvironmentVariablePasswordProvider:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "http",
  6. "uris": ["http://example.com/uri1", "http://example2.com/uri2"],
  7. "httpAuthenticationUsername": "username",
  8. "httpAuthenticationPassword": {
  9. "type": "environment",
  10. "variable": "HTTP_INPUT_SOURCE_PW"
  11. }
  12. },
  13. "inputFormat": {
  14. "type": "json"
  15. },
  16. ...
  17. },
  18. ...
  19. }
PropertyDescriptionDefaultRequired
typeSet the value to http.Noneyes
urisURIs of the input files. See below for the protocols allowed for URIs.Noneyes
httpAuthenticationUsernameUsername to use for authentication with specified URIs. Can be optionally used if the URIs specified in the spec require a Basic Authentication Header.Noneno
httpAuthenticationPasswordPasswordProvider to use with specified URIs. Can be optionally used if the URIs specified in the spec require a Basic Authentication Header.Noneno
systemFieldsJSON array of system fields to return as part of input rows. Possible values: file_uri (URI including scheme) and file_path (path component of URI).Noneno

You can only use protocols listed in the druid.ingestion.http.allowedProtocols property as HTTP input sources. The http and https protocols are allowed by default. See HTTP input source security configuration for more details.

Inline input source

The Inline input source can be used to read the data inlined in its own spec. It can be used for demos or for quickly testing out parsing and schema.

Sample spec:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "inline",
  6. "data": "0,values,formatted\n1,as,CSV"
  7. },
  8. "inputFormat": {
  9. "type": "csv"
  10. },
  11. ...
  12. },
  13. ...
PropertyDescriptionRequired
typeSet the value to inline.yes
dataInlined data to ingest.yes

Local input source

The Local input source is to support reading files directly from local storage, and is mainly intended for proof-of-concept testing. The Local input source is splittable and can be used by the Parallel task, where each worker task of index_parallel will read one or multiple files.

Sample spec:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "local",
  6. "filter" : "*.csv",
  7. "baseDir": "/data/directory",
  8. "files": ["/bar/foo", "/foo/bar"]
  9. },
  10. "inputFormat": {
  11. "type": "csv"
  12. },
  13. ...
  14. },
  15. ...
PropertyDescriptionRequired
typeSet the value to local.yes
filterA wildcard filter for files. See here for more information. Files matching the filter criteria are considered for ingestion. Files not matching the filter criteria are ignored.yes if baseDir is specified
baseDirDirectory to search recursively for files to be ingested. Empty files under the baseDir will be skipped.At least one of baseDir or files should be specified
filesFile paths to ingest. Some files can be ignored to avoid ingesting duplicate files if they are located under the specified baseDir. Empty files will be skipped.At least one of baseDir or files should be specified
systemFieldsJSON array of system fields to return as part of input rows. Possible values: file_uri (File URI starting with file:) and file_path (file path).None

Druid input source

The Druid input source is to support reading data directly from existing Druid segments, potentially using a new schema and changing the name, dimensions, metrics, rollup, etc. of the segment. The Druid input source is splittable and can be used by the Parallel task. This input source has a fixed input format for reading from Druid segments; no inputFormat field needs to be specified in the ingestion spec when using this input source.

PropertyDescriptionRequired
typeSet the value to druid.yes
dataSourceA String defining the Druid datasource to fetch rows fromyes
intervalA String representing an ISO-8601 interval, which defines the time range to fetch the data over.yes
filterSee Filters. Only rows that match the filter, if specified, will be returned.no

The Druid input source can be used for a variety of purposes, including:

  • Creating new datasources that are rolled-up copies of existing datasources.
  • Changing the partitioning or sorting of a datasource to improve performance.
  • Updating or removing rows using a transformSpec.

When using the Druid input source, the timestamp column shows up as a numeric field named __time set to the number of milliseconds since the epoch (January 1, 1970 00:00:00 UTC). It is common to use this in the timestampSpec, if you want the output timestamp to be equivalent to the input timestamp. In this case, set the timestamp column to __time and the format to auto or millis.

It is OK for the input and output datasources to be the same. In this case, newly generated data will overwrite the previous data for the intervals specified in the granularitySpec. Generally, if you are going to do this, it is a good idea to test out your reindexing by writing to a separate datasource before overwriting your main one. Alternatively, if your goals can be satisfied by compaction, consider that instead as a simpler approach.

An example task spec is shown below. It reads from a hypothetical raw datasource wikipedia_raw and creates a new rolled-up datasource wikipedia_rollup by grouping on hour, “countryName”, and “page”.

  1. {
  2. "type": "index_parallel",
  3. "spec": {
  4. "dataSchema": {
  5. "dataSource": "wikipedia_rollup",
  6. "timestampSpec": {
  7. "column": "__time",
  8. "format": "millis"
  9. },
  10. "dimensionsSpec": {
  11. "dimensions": [
  12. "countryName",
  13. "page"
  14. ]
  15. },
  16. "metricsSpec": [
  17. {
  18. "type": "count",
  19. "name": "cnt"
  20. }
  21. ],
  22. "granularitySpec": {
  23. "type": "uniform",
  24. "queryGranularity": "HOUR",
  25. "segmentGranularity": "DAY",
  26. "intervals": ["2016-06-27/P1D"],
  27. "rollup": true
  28. }
  29. },
  30. "ioConfig": {
  31. "type": "index_parallel",
  32. "inputSource": {
  33. "type": "druid",
  34. "dataSource": "wikipedia_raw",
  35. "interval": "2016-06-27/P1D"
  36. }
  37. },
  38. "tuningConfig": {
  39. "type": "index_parallel",
  40. "partitionsSpec": {
  41. "type": "hashed"
  42. },
  43. "forceGuaranteedRollup": true,
  44. "maxNumConcurrentSubTasks": 1
  45. }
  46. }
  47. }

Input sources - 图7info

Note: Older versions (0.19 and earlier) did not respect the timestampSpec when using the Druid input source. If you have ingestion specs that rely on this and cannot rewrite them, set druid.indexer.task.ignoreTimestampSpecForDruidInputSource to true to enable a compatibility mode where the timestampSpec is ignored.

The secondary partitioning method determines the requisite number of concurrent worker tasks that run in parallel to complete ingestion with the Combining input source. Set this value in maxNumConcurrentSubTasks in tuningConfig based on the secondary partitioning method:

  • range or single_dim partitioning: greater than or equal to 1
  • hashed or dynamic partitioning: greater than or equal to 2

For more information on the maxNumConcurrentSubTasks field, see Implementation considerations.

SQL input source

The SQL input source is used to read data directly from RDBMS. The SQL input source is splittable and can be used by the Parallel task, where each worker task will read from one SQL query from the list of queries. This input source does not support Split Hint Spec. Since this input source has a fixed input format for reading events, no inputFormat field needs to be specified in the ingestion spec when using this input source. Please refer to the Recommended practices section below before using this input source.

PropertyDescriptionRequired
typeSet the value to sql.Yes
databaseSpecifies the database connection details. The database type corresponds to the extension that supplies the connectorConfig support. The specified extension must be loaded into Druid:



You can selectively allow JDBC properties in connectURI. See JDBC connections security config for more details.
Yes
foldCaseToggle case folding of database column names. This may be enabled in cases where the database returns case insensitive column names in query results.No
sqlsList of SQL queries where each SQL query would retrieve the data to be indexed.Yes

The following is an example of an SQL input source spec:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "sql",
  6. "database": {
  7. "type": "mysql",
  8. "connectorConfig": {
  9. "connectURI": "jdbc:mysql://host:port/schema",
  10. "user": "user",
  11. "password": "password"
  12. }
  13. },
  14. "sqls": ["SELECT * FROM table1 WHERE timestamp BETWEEN '2013-01-01 00:00:00' AND '2013-01-01 11:59:59'", "SELECT * FROM table2 WHERE timestamp BETWEEN '2013-01-01 00:00:00' AND '2013-01-01 11:59:59'"]
  15. }
  16. },
  17. ...

The spec above will read all events from two separate SQLs for the interval 2013-01-01/2013-01-02. Each of the SQL queries will be run in its own sub-task and thus for the above example, there would be two sub-tasks.

Recommended practices

Compared to the other native batch input sources, SQL input source behaves differently in terms of reading the input data. Therefore, consider the following points before using this input source in a production environment:

  • During indexing, each sub-task would execute one of the SQL queries and the results are stored locally on disk. The sub-tasks then proceed to read the data from these local input files and generate segments. Presently, there isn’t any restriction on the size of the generated files and this would require the MiddleManagers or Indexers to have sufficient disk capacity based on the volume of data being indexed.

  • Filtering the SQL queries based on the intervals specified in the granularitySpec can avoid unwanted data being retrieved and stored locally by the indexing sub-tasks. For example, if the intervals specified in the granularitySpec is ["2013-01-01/2013-01-02"] and the SQL query is SELECT * FROM table1, SqlInputSource will read all the data for table1 based on the query, even though only data between the intervals specified will be indexed into Druid.

  • Pagination may be used on the SQL queries to ensure that each query pulls a similar amount of data, thereby improving the efficiency of the sub-tasks.

  • Similar to file-based input formats, any updates to existing data will replace the data in segments specific to the intervals specified in the granularitySpec.

Combining input source

The Combining input source lets you read data from multiple input sources. It identifies the splits from delegate input sources and uses a worker task to process each split. Use the Combining input source only if all the delegates are splittable and can be used by the Parallel task.

Similar to other input sources, the Combining input source supports a single inputFormat. Delegate input sources that require an inputFormat must have the same format for input data. If you include the Druid input source, the timestamp column is stored in the __time field. To correctly combine the data from the Druid input source with another source, ensure that other delegate input sources also store the timestamp column in __time.

PropertyDescriptionRequired
typeSet the value to combining.Yes
delegatesList of splittable input sources to read data from.Yes

The following is an example of a Combining input source spec:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "combining",
  6. "delegates" : [
  7. {
  8. "type": "local",
  9. "filter" : "*.csv",
  10. "baseDir": "/data/directory",
  11. "files": ["/bar/foo", "/foo/bar"]
  12. },
  13. {
  14. "type": "druid",
  15. "dataSource": "wikipedia",
  16. "interval": "2013-01-01/2013-01-02"
  17. }
  18. ]
  19. },
  20. "inputFormat": {
  21. "type": "csv"
  22. },
  23. ...
  24. },
  25. ...

Iceberg input source

Input sources - 图8info

To use the Iceberg input source, load the extension druid-iceberg-extensions.

You use the Iceberg input source to read data stored in the Iceberg table format. For a given table, the input source scans up to the latest Iceberg snapshot from the configured Hive catalog. Druid ingests the underlying live data files using the existing input source formats.

The Iceberg input source cannot be independent as it relies on the existing input sources to read from the data files. For example, if the warehouse associated with an Iceberg catalog is on S3, you must also load the druid-s3-extensions extension.

The following is a sample spec for a HDFS warehouse source:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "iceberg",
  6. "tableName": "iceberg_table",
  7. "namespace": "iceberg_namespace",
  8. "icebergCatalog": {
  9. "type": "hive",
  10. "warehousePath": "hdfs://warehouse/path",
  11. "catalogUri": "thrift://hive-metastore.x.com:8970",
  12. "catalogProperties": {
  13. "hive.metastore.connect.retries": "1",
  14. "hive.metastore.execute.setugi": "false",
  15. "hive.metastore.kerberos.principal": "KRB_PRINCIPAL",
  16. "hive.metastore.sasl.enabled": "true",
  17. "metastore.catalog.default": "catalog_test",
  18. "hadoop.security.authentication": "kerberos",
  19. "hadoop.security.authorization": "true"
  20. }
  21. },
  22. "icebergFilter": {
  23. "type": "interval",
  24. "filterColumn": "event_time",
  25. "intervals": [
  26. "2023-05-10T19:00:00.000Z/2023-05-10T20:00:00.000Z"
  27. ]
  28. },
  29. "warehouseSource": {
  30. "type": "hdfs"
  31. },
  32. "snapshotTime": "2023-06-01T00:00:00.000Z",
  33. },
  34. "inputFormat": {
  35. "type": "parquet"
  36. }
  37. },
  38. ...
  39. },
  40. ...

The following is a sample spec for a S3 warehouse source:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "iceberg",
  6. "tableName": "iceberg_table",
  7. "namespace": "iceberg_namespace",
  8. "icebergCatalog": {
  9. "type": "hive",
  10. "warehousePath": "s3://warehouse/path",
  11. "catalogUri": "thrift://hive-metastore.x.com:8970",
  12. "catalogProperties": {
  13. "hive.metastore.connect.retries": "1",
  14. "hive.metastore.execute.setugi": "false",
  15. "hive.metastore.kerberos.principal": "KRB_PRINCIPAL",
  16. "hive.metastore.sasl.enabled": "true",
  17. "metastore.catalog.default": "default_catalog",
  18. "fs.s3a.access.key" : "S3_ACCESS_KEY",
  19. "fs.s3a.secret.key" : "S3_SECRET_KEY",
  20. "fs.s3a.endpoint" : "S3_API_ENDPOINT"
  21. }
  22. },
  23. "icebergFilter": {
  24. "type": "interval",
  25. "filterColumn": "event_time",
  26. "intervals": [
  27. "2023-05-10T19:00:00.000Z/2023-05-10T20:00:00.000Z"
  28. ]
  29. },
  30. "warehouseSource": {
  31. "type": "s3",
  32. "endpointConfig": {
  33. "url": "teststore.aws.com",
  34. "signingRegion": "us-west-2a"
  35. },
  36. "clientConfig": {
  37. "protocol": "http",
  38. "disableChunkedEncoding": true,
  39. "enablePathStyleAccess": true,
  40. "forceGlobalBucketAccessEnabled": false
  41. },
  42. "properties": {
  43. "accessKeyId": {
  44. "type": "default",
  45. "password": "foo"
  46. },
  47. "secretAccessKey": {
  48. "type": "default",
  49. "password": "bar"
  50. }
  51. },
  52. }
  53. },
  54. "inputFormat": {
  55. "type": "parquet"
  56. }
  57. },
  58. ...
  59. },
PropertyDescriptionRequired
typeSet the value to iceberg.yes
tableNameThe Iceberg table name configured in the catalog.yes
namespaceThe Iceberg namespace associated with the table.yes
icebergFilterThe JSON Object that filters data files within a snapshot.no
icebergCatalogThe JSON Object used to define the catalog that manages the configured Iceberg table.yes
warehouseSourceThe JSON Object that defines the native input source for reading the data files from the warehouse.yes
snapshotTimeTimestamp in ISO8601 DateTime format that will be used to fetch the most recent snapshot as of this time.no

Catalog Object

The catalog object supports local and hive catalog types.

The following table lists the properties of a local catalog:

PropertyDescriptionRequired
typeSet this value to local.yes
warehousePathThe location of the warehouse associated with the catalogyes
catalogPropertiesMap of any additional properties that needs to be attached to the catalogno

The following table lists the properties of a hive catalog:

PropertyDescriptionRequired
typeSet this value to hive.yes
warehousePathThe location of the warehouse associated with the catalogyes
catalogUriThe URI associated with the hive catalogyes
catalogPropertiesMap of any additional properties that needs to be attached to the catalogno

Iceberg filter object

This input source provides the following filters: and, equals, interval, and or. You can use these filters to filter out data files from a snapshot, reducing the number of files Druid has to ingest.

equals Filter:

PropertyDescriptionRequired
typeSet this value to equals.yes
filterColumnThe name of the column from the Iceberg table schema to use for filtering.yes
filterValueThe value to filter on.yes

interval Filter:

PropertyDescriptionRequired
typeSet this value to interval.yes
filterColumnThe column name from the iceberg table schema based on which filtering needs to happenyes
intervalsA JSON array containing ISO 8601 interval strings. This defines the time ranges to filter on. The start interval is inclusive and the end interval is exclusive.yes

and Filter:

PropertyDescriptionRequired
typeSet this value to and.yes
filtersList of iceberg filters that needs to be AND-edyes

or Filter:

PropertyDescriptionRequired
typeSet this value to or.yes
filtersList of iceberg filters that needs to be OR-edyes

not Filter:

PropertyDescriptionRequired
typeSet this value to not.yes
filterThe iceberg filter on which logical NOT is appliedyes

range Filter:

PropertyDescriptionDefaultRequired
typeSet this value to range.Noneyes
filterColumnThe column name from the iceberg table schema based on which range filtering needs to happen.Noneyes
lowerLower bound value to match.Noneno. At least one of lower or upper must not be null.
upperUpper bound value to match.Noneno. At least one of lower or upper must not be null.
lowerOpenBoolean indicating if lower bound is open in the interval of values defined by the range (“>” instead of “>=”).falseno
upperOpenBoolean indicating if upper bound is open on the interval of values defined by range (“<” instead of “<=”).falseno

Delta Lake input source

Input sources - 图9info

To use the Delta Lake input source, load the extension druid-deltalake-extensions.

You can use the Delta input source to read data stored in a Delta Lake table. For a given table, the input source scans the latest snapshot from the configured table. Druid ingests the underlying delta files from the table.

PropertyDescriptionRequired
typeSet this value to delta.yes
tablePathThe location of the Delta table.yes
filterThe JSON Object that filters data files within a snapshot.no

Delta filter object

You can use these filters to filter out data files from a snapshot, reducing the number of files Druid has to ingest from a Delta table. This input source provides the following filters: and, or, not, =, >, >=, <, <=.

When a filter is applied on non-partitioned columns, the filtering is best-effort as the Delta Kernel solely relies on statistics collected when the non-partitioned table is created. In this scenario, this Druid connector may ingest data that doesn’t match the filter. To guarantee that the Delta Kernel prunes out unnecessary column values, only use filters on partitioned columns.

and filter:

PropertyDescriptionRequired
typeSet this value to and.yes
filtersList of Delta filter predicates that get evaluated using logical AND where both conditions need to be true. and filter requires two filter predicates.yes

or filter:

PropertyDescriptionRequired
typeSet this value to or.yes
filtersList of Delta filter predicates that get evaluated using logical OR where only one condition needs to be true. or filter requires two filter predicates.yes

not filter:

PropertyDescriptionRequired
typeSet this value to not.yes
filterThe Delta filter predicate that gets evaluated using logical NOT. not filter requires one filter predicate.yes

= filter:

PropertyDescriptionRequired
typeSet this value to =.yes
columnThe table column to apply the filter on.yes
valueThe value to use in the filter.yes

> filter:

PropertyDescriptionRequired
typeSet this value to >.yes
columnThe table column to apply the filter on.yes
valueThe value to use in the filter.yes

>= filter:

PropertyDescriptionRequired
typeSet this value to >=.yes
columnThe table column to apply the filter on.yes
valueThe value to use in the filter.yes

< filter:

PropertyDescriptionRequired
typeSet this value to <.Yes
columnThe table column to apply the filter on.Yes
valueThe value to use in the filter.Yes

<= filter:

PropertyDescriptionRequired
typeSet this value to <=.yes
columnThe table column to apply the filter on.yes
valueThe value to use in the filter.yes

The following is a sample spec to read all records from the Delta table /delta-table/foo:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "delta",
  6. "tablePath": "/delta-table/foo"
  7. },
  8. }

The following is a sample spec to read records from the Delta table /delta-table/foo to select records where name = 'Employee4' and age >= 30:

  1. ...
  2. "ioConfig": {
  3. "type": "index_parallel",
  4. "inputSource": {
  5. "type": "delta",
  6. "tablePath": "/delta-table/foo",
  7. "filter": {
  8. "type": "and",
  9. "filters": [
  10. {
  11. "type": "=",
  12. "column": "name",
  13. "value": "Employee4"
  14. },
  15. {
  16. "type": ">=",
  17. "column": "age",
  18. "value": "30"
  19. }
  20. ]
  21. }
  22. },
  23. }