--- title: Upload CSV-format lookup tables source: https://docs.newrelic.com/docs/logs/ui-data/lookup-tables-ui --- Our **lookups** feature lets you enrich your log data, and other New Relic-stored data, with data about your business that you define in a CSV file. ## Why use lookups? [#overview] When you upload a lookup table, you can then use that data to enrich your queries of New Relic data. For example, you might upload a table that maps host IDs to human-readable host names, and then use that to create a chart that displays the human-readable host names. Lookup tables help you: - Query data that isn't present in your New Relic account - Make your telemetry data easier to understand - Group data in custom ways For examples of queries using lookups, see [How to query lookup table data](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/nrql-query-tutorials/lookups). ## Add and manage tables [#add-table] You can add and manage lookup tables through the [UI](#lookup-ui) or the [NRQL Lookups API](#lookups-service-api). Some tips when adding a table: - The table name is what you'll use to reference that table when you write a [NRQL query](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/nrql-query-tutorials/lookups). - Table data isn't obfuscated, so avoid uploading sensitive information. - It can take several minutes for an added or updated table to be available in a NRQL query. When you delete a table, that data is no longer available in NRQL queries, so you should try to make sure a deleted table's data isn't being used in important dashboards. [Learn more table format requirements and other details](#requirements). ### Using the lookup tables UI [#lookup-ui] ![Upload a csv lookup table](https://docs.newrelic.com/images/logs_screenshot-crop_lookup-table-ui.webp "Upload a csv lookup table") The UI for uploading lookup tables is located in the logs UI, but you can use your lookup table data when querying any data type, not just logs. To find the lookup table UI: From [one.newrelic.com](https://one.newrelic.com), click **Logs**, and then click **Lookup tables**. From there, you can upload, download, update, and delete tables. ### Using the NRQL Lookups API [#lookups-service-api] Alternatively, you can add and manage tables using the [NRQL Lookups API](https://docs.newrelic.com/docs/apis/lookups-service-api/lookups-service-api). The NRQL Lookups API supports uploading lookup tables as a CSV file and a JSON object. ## CSV value parsing [#valuetypes] When a value is read from a CSV file, the system will attempt to parse the value to a boolean, number, or string value. **CSV Parsing Rules** | Rule | CSV value | Interpreted value | Interpreted type | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Value Types - String: This is the default type for any value, unless criteria are met to interpret it as a number or boolean. - Boolean: If the value is equal to true or false, case-insensitive, the value is parsed as a boolean. - Numbers: Value parsing can interpret integer and float values, with the following stipulations: - Scientific notation is supported. Values including scientific notation are parsed to a float value. - If the numeric value contains a decimal or the letter E, it will parse to a float value. Otherwise, it will parse to an integer value. - Maximum integer supported: 9223372036854775807 (Note, numbers higher than 9007199254740991 may lose precision when viewed in a web browser) - Minimum integer supported: -9223372036854775808 (Note, numbers lower than -9007199254740991 may lose precision when viewed in a web browser) - When interpreting a float value, the integer part of the value (the part before the decimal in the original string value) must lie within the maximum/minimum supported integer bounds. - If the value contains a decimal, there must be at least one numeric digit before and after the decimal. - Signed values: - Values that start with a numeric digit or a plus "+" sign are considered positive numbers. - Values that start with a minus "-" sign or are surrounded in parentheses are considered negative numbers. - Original values are never trimmed. Whitespace at the beginning or end of a value will cause it to be parsed as a string. | `abc` `a b c` `123` `1.23` `1.23E-3` `true` ` abc ` ` 123 ` ` true ` | `abc` `a b c` `123` `1.23` `1.23E-3` `true` ` abc ` ` 123 ` ` true ` | string string number number number boolean string string string | | Double quotes - Any value can be wrapped in double quotes. Double quotes are required if the value contains a comma or starts with a double quote. - Within a double-quoted value, two double quotes in a row will parse to a single double quote in the resulting value. - Wrapping a value in double quotes does not force it to be interpreted as a string. Parsing of the value still occurs. | `"abc"` `"a,b,c"` `"a b c"` `"""abc"""` `"a,""b"",c"` `"a ""b"" c"` `"""123"""` `"""true"""` `"123"` `"true"` | `abc` `a,b,c` `a b c` `"abc"` `"a,"b",c"` `a "b" c` `"123"` `"true"` `123` `true` | string string string string string string string string number boolean | | Forced strings - To force a value to be interpreted as a string, prefix the value with a single quote. - If the value is double-quoted, the single quote needs to be after the opening double quote. - If the string value needs to start with a single quote, you'll need two single quotes, because the first one forces the value to be interpreted as a string. | `'abc` `'123` `'true` `"'abc"` `"'123"` `"'true"` `''abc'` `''123'` `''true'` | `abc` `123` `true` `abc` `123` `true` `'abc'` `'123'` `'true'` | string string string string string string string string string | ## Query your data [#query] If you're ready to use your table in a query, see [How to query lookup table data](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/nrql-query-tutorials/lookups). ## Requirements and technical details [#requirements] Some more details about lookup tables: - To add or edit tables, users need to be [core or full platform users](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-type/#user-type-capabilities). - Tables can only be queried from the [account](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/new-relic-account-structure/#organization-accounts) in which the table was uploaded. - Each [account](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/new-relic-account-structure/#organization-accounts) has a limit of 250 lookup tables. - Lookup table data can't be used in NRQL alert conditions. - Lookup tables have indefinite data retention by default. In addition to [the general requirements for a CSV file](https://www.rfc-editor.org/rfc/rfc4180), here are our requirements for uploading lookup table files: - Each row must have the same number of columns as the header and there must be at least two columns. - Table names must conform to [the rules for event names](https://docs.newrelic.com/docs/data-apis/ingest-apis/event-api/introduction-event-api/#limits) - Do not use [reserved words](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/data-requirements-limits-custom-event-data/#reserved-words) for table names or column header values. - Max file size: 4 MB - Max of 20,000 rows