techdocsmith commented on code in PR #16725: URL: https://github.com/apache/druid/pull/16725#discussion_r1695761995
########## docs/querying/lookups-cached-global.md: ########## @@ -22,21 +26,22 @@ title: "Globally Cached Lookups" ~ under the License. --> +Globally cached lookups all draw from the same cache pool, allowing each Druid process to have a fixed cache pool that can be used by cached lookups. + To use this Apache Druid extension, [include](../configuration/extensions.md#loading-extensions) `druid-lookups-cached-global` in the extensions load list. ## Configuration -:::info - Static configuration is no longer supported. Lookups can be configured through - [dynamic configuration](./lookups.md#configuration). -::: Globally cached lookups are appropriate for lookups which are not possible to pass at query time due to their size, or are not desired to be passed at query time because the data is to reside in and be handled by the Druid servers, and are small enough to reasonably populate in-memory. This usually means tens to tens of thousands of entries per lookup. -Globally cached lookups all draw from the same cache pool, allowing each process to have a fixed cache pool that can be used by cached lookups. +:::info + Druid no longer supports static lookup configuration. You can configure lookups through + [dynamic configuration](./lookups.md#configuration). +::: Review Comment: how long has this been out of support? Can we just not mention now? ########## docs/querying/lookups-cached-global.md: ########## @@ -22,21 +26,22 @@ title: "Globally Cached Lookups" ~ under the License. --> +Globally cached lookups all draw from the same cache pool, allowing each Druid process to have a fixed cache pool that can be used by cached lookups. Review Comment: ```suggestion Globally cached lookups all draw from the same cache pool, allowing each Druid service to have a fixed cache pool that can be used by cached lookups. ``` we're opting for service over process now. ########## docs/querying/lookups-cached-global.md: ########## @@ -149,32 +153,32 @@ Where the Coordinator endpoint `/druid/coordinator/v1/lookups/realtime_customer2 } ``` -## Cache Settings +## Cache settings Lookups are cached locally on Historical processes. The following are settings used by the processes which service queries when setting namespaces (Broker, Peon, Historical) |Property|Description|Default| |--------|-----------|-------| -|`druid.lookup.namespace.cache.type`|Specifies the type of caching to be used by the namespaces. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| -|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. This number may need to be scaled up, if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| -|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to be stored on an on-heap buffer.|100,000| +|`druid.lookup.namespace.cache.type`|Specifies the type of caching for the namespaces to use. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| +|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. You may need to increase this number if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| +|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to store on an on-heap buffer.|100,000| -The cache is populated in different ways depending on the settings below. In general, most namespaces employ -a `pollPeriod` at the end of which time they poll the remote resource of interest for updates. +Druid populates the cache in different ways depending on the settings below. In general, most namespaces employ +a `pollPeriod` at the end of which they poll the remote resource of interest for updates. -`onHeap` uses `ConcurrentMap`s in the java heap, and thus affects garbage collection and heap sizing. +`onHeap` uses `ConcurrentMap`s in the java heap, and therefore affects garbage collection and heap sizing. Review Comment: ```suggestion `onHeap` uses `ConcurrentMap`s in the java heap which affects garbage collection and heap sizing. ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -149,32 +153,32 @@ Where the Coordinator endpoint `/druid/coordinator/v1/lookups/realtime_customer2 } ``` -## Cache Settings +## Cache settings Lookups are cached locally on Historical processes. The following are settings used by the processes which service queries when setting namespaces (Broker, Peon, Historical) |Property|Description|Default| |--------|-----------|-------| -|`druid.lookup.namespace.cache.type`|Specifies the type of caching to be used by the namespaces. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| -|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. This number may need to be scaled up, if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| -|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to be stored on an on-heap buffer.|100,000| +|`druid.lookup.namespace.cache.type`|Specifies the type of caching for the namespaces to use. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| +|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. You may need to increase this number if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| +|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to store on an on-heap buffer.|100,000| -The cache is populated in different ways depending on the settings below. In general, most namespaces employ -a `pollPeriod` at the end of which time they poll the remote resource of interest for updates. +Druid populates the cache in different ways depending on the settings below. In general, most namespaces employ Review Comment: ```suggestion Druid populates the cache in different ways depending on the following settings. In general, most namespaces employ ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -22,21 +26,22 @@ title: "Globally Cached Lookups" ~ under the License. --> +Globally cached lookups all draw from the same cache pool, allowing each Druid process to have a fixed cache pool that can be used by cached lookups. + To use this Apache Druid extension, [include](../configuration/extensions.md#loading-extensions) `druid-lookups-cached-global` in the extensions load list. ## Configuration -:::info - Static configuration is no longer supported. Lookups can be configured through - [dynamic configuration](./lookups.md#configuration). -::: Globally cached lookups are appropriate for lookups which are not possible to pass at query time due to their size, or are not desired to be passed at query time because the data is to reside in and be handled by the Druid servers, and are small enough to reasonably populate in-memory. This usually means tens to tens of thousands of entries per lookup. Review Comment: ```suggestion Use globally cached lookup in the following scenarios: - The lookup is too large to pass at query time. - You want the lookup data to reside in a Druid data source handled by Druid and the lookup is small enough to reasonably reside in memory--between tens and tens of thousand of entries per lookup. ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -149,32 +153,32 @@ Where the Coordinator endpoint `/druid/coordinator/v1/lookups/realtime_customer2 } ``` -## Cache Settings +## Cache settings Lookups are cached locally on Historical processes. The following are settings used by the processes which service queries when setting namespaces (Broker, Peon, Historical) |Property|Description|Default| |--------|-----------|-------| -|`druid.lookup.namespace.cache.type`|Specifies the type of caching to be used by the namespaces. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| -|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. This number may need to be scaled up, if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| -|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to be stored on an on-heap buffer.|100,000| +|`druid.lookup.namespace.cache.type`|Specifies the type of caching for the namespaces to use. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| +|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. You may need to increase this number if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| +|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to store on an on-heap buffer.|100,000| -The cache is populated in different ways depending on the settings below. In general, most namespaces employ -a `pollPeriod` at the end of which time they poll the remote resource of interest for updates. +Druid populates the cache in different ways depending on the settings below. In general, most namespaces employ +a `pollPeriod` at the end of which they poll the remote resource of interest for updates. -`onHeap` uses `ConcurrentMap`s in the java heap, and thus affects garbage collection and heap sizing. +`onHeap` uses `ConcurrentMap`s in the java heap, and therefore affects garbage collection and heap sizing. `offHeap` uses an on-heap buffer and MapDB using memory-mapped files in the java temporary directory. -So if total number of entries in the `cachedNamespace` is in excess of the buffer's configured capacity, the extra will be kept in memory as page cache, and paged in and out by general OS tunings. -It's highly recommended that `druid.lookup.namespace.numBufferedEntries` is set when using `offHeap`, the value should be chosen from the range between 10% and 50% of the number of entries in the lookup. +Therefore, if the total number of entries in the `cachedNamespace` exceeds the buffer's configured capacity, the extra entries are kept in memory as page cache, and paged in and out by general OS tunings. Review Comment: ```suggestion Therefore, if the total number of entries in the `cachedNamespace` exceeds the buffer's configured capacity, Druid maintains the extra entries in memory as page cache, and paged in and out according to general operating system tunings. ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -341,20 +351,26 @@ The `simpleJson` lookupParseSpec does not take any parameters. It is simply a li ### JDBC lookup -The JDBC lookups will poll a database to populate its local cache. If the `tsColumn` is set it must be able to accept comparisons in the format `'2015-01-01 00:00:00'`. For example, the following must be valid SQL for the table `SELECT * FROM some_lookup_table WHERE timestamp_column > '2015-01-01 00:00:00'`. If `tsColumn` is set, the caching service will attempt to only poll values that were written *after* the last sync. If `tsColumn` is not set, the entire table is pulled every time. +The JDBC lookups polls a database to populate its local cache. If the `tsColumn` is defined it must be able to accept comparisons in the format `'2015-01-01 00:00:00'`. Review Comment: ```suggestion The JDBC lookups polls a database to populate the local cache. If the `tsColumn` is defined it must be able to accept comparisons in the format `'2015-01-01 00:00:00'`. ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -149,32 +153,32 @@ Where the Coordinator endpoint `/druid/coordinator/v1/lookups/realtime_customer2 } ``` -## Cache Settings +## Cache settings Lookups are cached locally on Historical processes. The following are settings used by the processes which service queries when setting namespaces (Broker, Peon, Historical) |Property|Description|Default| |--------|-----------|-------| -|`druid.lookup.namespace.cache.type`|Specifies the type of caching to be used by the namespaces. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| -|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. This number may need to be scaled up, if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| -|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to be stored on an on-heap buffer.|100,000| +|`druid.lookup.namespace.cache.type`|Specifies the type of caching for the namespaces to use. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| +|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. You may need to increase this number if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| +|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to store on an on-heap buffer.|100,000| -The cache is populated in different ways depending on the settings below. In general, most namespaces employ -a `pollPeriod` at the end of which time they poll the remote resource of interest for updates. +Druid populates the cache in different ways depending on the settings below. In general, most namespaces employ +a `pollPeriod` at the end of which they poll the remote resource of interest for updates. -`onHeap` uses `ConcurrentMap`s in the java heap, and thus affects garbage collection and heap sizing. +`onHeap` uses `ConcurrentMap`s in the java heap, and therefore affects garbage collection and heap sizing. `offHeap` uses an on-heap buffer and MapDB using memory-mapped files in the java temporary directory. -So if total number of entries in the `cachedNamespace` is in excess of the buffer's configured capacity, the extra will be kept in memory as page cache, and paged in and out by general OS tunings. -It's highly recommended that `druid.lookup.namespace.numBufferedEntries` is set when using `offHeap`, the value should be chosen from the range between 10% and 50% of the number of entries in the lookup. +Therefore, if the total number of entries in the `cachedNamespace` exceeds the buffer's configured capacity, the extra entries are kept in memory as page cache, and paged in and out by general OS tunings. +We strongly recommended that you set `druid.lookup.namespace.numBufferedEntries` when using `offHeap`. Select a value between 10% and 50% of the number of entries in the lookup. ## Supported lookups -For additional lookups, please see our [extensions list](../configuration/extensions.md). +For information on additional lookups, please see the [extensions list](../configuration/extensions.md). Review Comment: ```suggestion For information on additional lookups, refer to the [extensions list](../configuration/extensions.md). ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -210,43 +214,48 @@ The remapping values for each globally cached lookup can be specified by a JSON |Property|Description|Required|Default| |--------|-----------|--------|-------| -|`pollPeriod`|Period between polling for updates|No|0 (only once)| -|`uri`|URI for the lookup file. Can be a file, HDFS, S3 or GCS path|Either `uri` or `uriPrefix` must be set|None| -|`uriPrefix`|A URI prefix that specifies a directory or other searchable resource where lookup files are located |Either `uri` or `uriPrefix` must be set|None| -|`fileRegex`|Optional regex for matching the file name under `uriPrefix`. Only used if `uriPrefix` is used|No|`".*"`| -|`namespaceParseSpec`|How to interpret the data at the URI|Yes|| -|`maxHeapPercentage`|The maximum percentage of heap size that the lookup should consume. If the lookup grows beyond this size, warning messages will be logged in the respective service logs.|No|10% of JVM heap size| +|`pollPeriod`|Time period between polling for updates, in ms.|No|0 (only once)| +|`uri`|URI for the lookup file. Can be a file, HDFS, S3 or GCS path.|You must define either `uri` or `uriPrefix`.*|None| +|`uriPrefix`|A URI prefix that specifies a directory or other searchable resource where lookup files are located.|You must define either `uri` or `uriPrefix`.*|None| +|`fileRegex`|Optional regex for matching the file name under `uriPrefix`. Only used if `uriPrefix` is defined.|No|`".*"`| +|`namespaceParseSpec`|How to interpret the data at the URI.|Yes|| +|`maxHeapPercentage`|The maximum percentage of heap size for the lookup to consume. If the lookup grows beyond this size, Druid logs warning messages in the respective service logs.|No|10% of JVM heap size| -One of either `uri` or `uriPrefix` must be specified, as either a local file system (file://), HDFS (hdfs://), S3 (s3://) or GCS (gs://) location. HTTP location is not currently supported. +*Define `uri` or `uriPrefix` as either a local file system (`file://`), HDFS (`hdfs://`), S3 (`s3://`) or GCS (`gs://`) location. Druid doesn't support HTTP location. -The `pollPeriod` value specifies the period in ISO 8601 format between checks for replacement data for the lookup. If the source of the lookup is capable of providing a timestamp, the lookup will only be updated if it has changed since the prior tick of `pollPeriod`. A value of 0, an absent parameter, or `null` all mean populate once and do not attempt to look for new data later. Whenever an poll occurs, the updating system will look for a file with the most recent timestamp and assume that one with the most recent data set, replacing the local cache of the lookup data. +The `pollPeriod` value specifies the period in ISO 8601 format between checks for replacement data for the lookup. If the source of the lookup is capable of providing a timestamp, the lookup is only updated if it has changed since the prior tick of `pollPeriod`. A value of 0, an absent parameter, or `null` all direct Druid to populate the lookup once and not attempt to look for new data later. Review Comment: ```suggestion The `pollPeriod` value specifies the period in ISO 8601 format between checks for replacement data for the lookup. If the source of the lookup provides a timestamp, Druid only updates the lookup when the lookup has changed since the prior `pollPeriod` timestamp. A value of 0, an absent parameter, or `null` all direct Druid to populate the lookup once without attempting to check again for new data. ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -210,43 +214,48 @@ The remapping values for each globally cached lookup can be specified by a JSON |Property|Description|Required|Default| |--------|-----------|--------|-------| -|`pollPeriod`|Period between polling for updates|No|0 (only once)| -|`uri`|URI for the lookup file. Can be a file, HDFS, S3 or GCS path|Either `uri` or `uriPrefix` must be set|None| -|`uriPrefix`|A URI prefix that specifies a directory or other searchable resource where lookup files are located |Either `uri` or `uriPrefix` must be set|None| -|`fileRegex`|Optional regex for matching the file name under `uriPrefix`. Only used if `uriPrefix` is used|No|`".*"`| -|`namespaceParseSpec`|How to interpret the data at the URI|Yes|| -|`maxHeapPercentage`|The maximum percentage of heap size that the lookup should consume. If the lookup grows beyond this size, warning messages will be logged in the respective service logs.|No|10% of JVM heap size| +|`pollPeriod`|Time period between polling for updates, in ms.|No|0 (only once)| +|`uri`|URI for the lookup file. Can be a file, HDFS, S3 or GCS path.|You must define either `uri` or `uriPrefix`.*|None| +|`uriPrefix`|A URI prefix that specifies a directory or other searchable resource where lookup files are located.|You must define either `uri` or `uriPrefix`.*|None| +|`fileRegex`|Optional regex for matching the file name under `uriPrefix`. Only used if `uriPrefix` is defined.|No|`".*"`| +|`namespaceParseSpec`|How to interpret the data at the URI.|Yes|| +|`maxHeapPercentage`|The maximum percentage of heap size for the lookup to consume. If the lookup grows beyond this size, Druid logs warning messages in the respective service logs.|No|10% of JVM heap size| -One of either `uri` or `uriPrefix` must be specified, as either a local file system (file://), HDFS (hdfs://), S3 (s3://) or GCS (gs://) location. HTTP location is not currently supported. +*Define `uri` or `uriPrefix` as either a local file system (`file://`), HDFS (`hdfs://`), S3 (`s3://`) or GCS (`gs://`) location. Druid doesn't support HTTP location. -The `pollPeriod` value specifies the period in ISO 8601 format between checks for replacement data for the lookup. If the source of the lookup is capable of providing a timestamp, the lookup will only be updated if it has changed since the prior tick of `pollPeriod`. A value of 0, an absent parameter, or `null` all mean populate once and do not attempt to look for new data later. Whenever an poll occurs, the updating system will look for a file with the most recent timestamp and assume that one with the most recent data set, replacing the local cache of the lookup data. +The `pollPeriod` value specifies the period in ISO 8601 format between checks for replacement data for the lookup. If the source of the lookup is capable of providing a timestamp, the lookup is only updated if it has changed since the prior tick of `pollPeriod`. A value of 0, an absent parameter, or `null` all direct Druid to populate the lookup once and not attempt to look for new data later. -The `namespaceParseSpec` can be one of a number of values. Each of the examples below would rename foo to bar, baz to bat, and buck to truck. All parseSpec types assumes each input is delimited by a new line. See below for the types of parseSpec supported. +Whenever a poll occurs, the updating system looks for a file with the most recent timestamp and assumes that is the one with the most recent data set, using it to replace the local cache of the lookup data. Review Comment: ```suggestion When Druid polls the lookup source, the updating system treats the file with the most recent timestamp as the one with the most recent data set and replace the local cache of the lookup data with the file contents. ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -149,32 +153,32 @@ Where the Coordinator endpoint `/druid/coordinator/v1/lookups/realtime_customer2 } ``` -## Cache Settings +## Cache settings Lookups are cached locally on Historical processes. The following are settings used by the processes which service queries when setting namespaces (Broker, Peon, Historical) |Property|Description|Default| |--------|-----------|-------| -|`druid.lookup.namespace.cache.type`|Specifies the type of caching to be used by the namespaces. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| -|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. This number may need to be scaled up, if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| -|`druid.lookup.namespace.numBufferedEntries`|If using off-heap caching, the number of records to be stored on an on-heap buffer.|100,000| +|`druid.lookup.namespace.cache.type`|Specifies the type of caching for the namespaces to use. May be one of [`offHeap`, `onHeap`]. `offHeap` uses a temporary file for off-heap storage of the namespace (memory mapped files). `onHeap` stores all cache on the heap in standard java map types.|`onHeap`| +|`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. You may need to increase this number if you have a lot of lookups and they take long time to extract, to avoid timeouts.|2| Review Comment: ```suggestion |`druid.lookup.namespace.numExtractionThreads`|The number of threads in the thread pool dedicated for lookup extraction and updates. If you have a lot of lookups and they take long time to extract, increase this number to avoid timeouts.|2| ``` ########## docs/querying/lookups-cached-global.md: ########## @@ -317,21 +327,21 @@ truck|something,3|buck } ``` -With customJson parsing, if the value field for a particular row is missing or null then that line will be skipped, and -will not be included in the lookup. +With `customJson` parsing, if the value field for a particular row is missing or null Druid skips that line and doesn't include it in the lookup. #### simpleJson lookupParseSpec -The `simpleJson` lookupParseSpec does not take any parameters. It is simply a line delimited JSON file where the field is the key, and the field's value is the value. -*example input* +The `simpleJson` `lookupParseSpec` doesn't take any parameters. It's simply a line-delimited JSON file where the field is the key, and the field's value is the value. Review Comment: ```suggestion The `simpleJson` `lookupParseSpec` doesn't take any parameters. It's simply a newline-delimited JSON file where the field is the key, and the field's value is the value. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
