Available: readFile() v1.130.0

The readFile() function is available from v1.130.0

Allows you to use a CSV Lookup File as data input for your query. Use this function to search the content of your .csv file.

readFile() should be used as the first function in your query (whether a primary query or subquery as part of a join).

ParameterTypeRequiredDefault ValueDescription
file[a]filerequired   File name to use as input.
includestringoptional[b]   Specifies the column names to read in the lookup file. If no argument is given, all columns are included.
limitnumberoptional[b]   Limits the number of rows returned. Use limit=N to preview the first N rows of the file.
  Minimum1 

[a] The parameter name file can be omitted.

[b] Optional parameters use their default value unless explicitly set.

Hide omitted argument names for this function

Show omitted argument names for this function

When using this function, the file should exist, either because the file has previously been uploaded (using Uploading Files) or included as part of an installed package.

When reading a file from a package, the package name should be specified in addition to the filename. For example:

logscale
readFile("falcon/investigate/logoninfo.csv")

For more information on referring to package resources, see Referencing Package Assets.

If you're aiming to preview the content of large files, we recommend always including the limit parameter to ensure optimal UI performance. However, when the file is utilized as data input for further manipulation, the limit parameter can be omitted.

readFile() Examples

Click + next to an example below to get the full details.

Preview Content in a Lookup File With readFile()

Preview content in a lookup file in the search portion of a repo without having to match the lookup against data

Query
logscale
readFile("host_names.csv")
Introduction

In this example, the readFile() function is used to look up a host_names.csv file just to preview the content in it.

Example incoming data might look like this: 

|--------------------|
| host_name, host_id |
| DESKTOP-VSKPBK8, 1 |
| FINANCE, 2         |
| homer-xubuntu, 3   |
| logger, 4          |
| DESKTOP-1, 5       |
| DESKTOP-2, 6       |
| DESKTOP-3, 7       |
|--------------------|
Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    readFile("host_names.csv")

    Displays the content of the .csv file.

    If you aim to preview the content of large files, we recommend always including the limit parameter to ensure optimal UI performance. For example: readFile("host_names.csv", limit=5). However, if the file is utilized as data input for further manipulation, the limit parameter can be omitted.

    Notice that if reading a file from a package, then the package name should be specified in addition to the filename. For example: readFile("falcon/investigate/logoninfo.csv").

  3. Event Result set.

Summary and Results

The query is used to preview content in CSV Lookup Files. After previewing the content with the readFile() function, it is possible to use the data for further manipulation, for example combine it with count() to count the rows, select() to filter data, join() to match data, etc. The readFile() function can also be used to read tables defined with the defineTable() function.

Sample output from the incoming example data:

host_idhost_name
1DESKTOP-VSKPBK8
2FINANCE
3homer-xubuntu
4logger
5DESKTOP-1
6DESKTOP-2
7DESKTOP-3

Sample output from the incoming example data with limit parameter:

host_idhost_name
1DESKTOP-VSKPBK8
2FINANCE
3homer-xubuntu
4logger
5DESKTOP-1

Preview Content in a Lookup File With readFile() and Filter With !join()

Preview content in a lookup file in the search portion of a repo and filter for specific data with the !join() function

Query
logscale
readFile("host_names.csv")
| !join(query={groupBy(host_name)}, field=host_name, key=host_name, include=[host_name, id])
Introduction

In this example, the readFile() function is used to look up a host_names.csv file, and then filter for host names that do not send any logs.

Example incoming data might look like this: 

|--------------------|
| host_name, host_id |
| DESKTOP-VSKPBK8, 1 |
| FINANCE, 2         |
| homer-xubuntu, 3   |
| logger, 4          |
| DESKTOP-1, 5       |
| DESKTOP-2, 6       |
| DESKTOP-3, 7       |
|--------------------|
Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    readFile("host_names.csv")

    Displays the content of the .csv file.

  3. logscale
    | !join(query={groupBy(host_name)}, field=host_name, key=host_name, include=[host_name, id])

    Filters for host names that do not send any logs.

  4. Event Result set.

Summary and Results

The query is used to preview content in CSV Lookup Files, and then filter for host names that do not send any logs.

Sample output from the incoming example data:

host_idhost_name
5DESKTOP-1
6DESKTOP-2
7DESKTOP-3