Scheduled Search

Scheduled search lets you save a FuseQL query and run it automatically on a schedule you define, such as every hour or every day at midnight. Each run delivers its results to a notification you choose, so you can monitor your data without running the query by hand.

Overview

Each scheduled run delivers results to one of two notification types:

  • Email - Recipients receive an email that previews the beginning of the result table inline, with the full result set attached as a CSV file.

  • Lookup table - Results are written to a lookup table, either merged with the current contents or replacing them completely. You can write to an existing lookup table or create a new one while you configure the scheduled search.

An optional threshold controls whether the notification fires. For example, with an hourly schedule, recipients receive an email (or the lookup table is updated) only when the threshold is met at that scheduled tick.

Scheduled search follows folder-based RBAC. Anyone with the correct folder permissions can create, edit, delete, pause, and resume a scheduled search.

Configure SMTP for email delivery

Before a scheduled search can deliver results by email, your cluster must have an SMTP configuration. Kloudfuse uses one cluster-wide SMTP block for both Grafana alert emails and scheduled-search emails, so this only needs to be set up once.

SMTP is required only for the Email notification type. The Lookup table notification does not use SMTP.

Add the following global.smtp block to your cluster values file (custom-values.yaml), using the values for your own SMTP provider:

global:
  smtp:
    enabled: true
    host: smtp.gmail.com    (1)
    port: 587               (2)
    fromAddress: no-reply@example.com    (3)
    fromName: KfuseAlerts
    skipTLSVerify: false
    existingSecret: smtp-secret
    userKey: user
    passwordKey: password
yaml
1 The SMTP server host for your provider. smtp.gmail.com is shown as an example; use your own provider’s host.
2 The SMTP port for your provider (commonly 587 for STARTTLS or 465 for SSL).
3 Replace with your own SMTP sender address.

The existingSecret field references a Kubernetes secret that holds your SMTP username and password. The credential values themselves live only in the secret; the values file just points at them:

  • existingSecret is the name of the secret. You can name the secret anything you want, as long as this value matches the name of the secret you create.

  • userKey is the name of the key within the secret that holds the SMTP username.

  • passwordKey is the name of the key within the secret that holds the SMTP password.

Create the secret in the Kloudfuse namespace before deploying, using key names that match userKey and passwordKey:

kubectl -n kfuse create secret generic smtp-secret \
  --from-literal=user=<smtp-username> \
  --from-literal=password=<smtp-password>

Create a Scheduled Search

The Create scheduled search page is divided into five panels: Details, Query, Notification, Schedule, and Threshold. Name, query, notification, schedule, and time window are required; the threshold is optional.

  1. In the top navigation, hover over Logs and select Scheduled Searches.

  2. Click Create search in the top right of the page.

  3. In the Details panel:

    1. In Name, enter a name for the scheduled search, for example my_scheduled_search. The name does not have to be unique; each scheduled search has its own unique ID.

    2. In Folder, select the folder to place the scheduled search in. The default is Root. When RBAC is enabled, select a folder you have permissions for. To create a folder, click + New.

  4. In the Query panel, enter the query to run at each scheduled tick in FuseQL query, for example level="error" | count by (source).

    Build and test the query in the Logs Explorer first, then paste it here.

  5. In the Notification panel, choose where results are delivered:

  6. In the Schedule panel, set how often the search runs under Schedule (cron):

    • Select Preset, then choose a schedule from the list: Every 15 minutes, Every 30 minutes, Every hour, Every 6 hours, Every 12 hours, Daily at midnight, or Weekly on Sunday.

    • Or select Custom, then enter a cron expression. See Custom cron expressions.

      Below the schedule, the panel describes the schedule in words and lists the Next runs (local time) so you can confirm it before you save. Schedules are evaluated in UTC, and a search runs no more often than every 15 minutes.

  7. Under Time window (look-back), set how far back each run queries, relative to when it fires:

    • Select a preset from the list, from Last 15 minutes to Last 7 days.

    • Or select Custom… and enter the look-back in seconds.

      The help text above the field shows the maximum look-back for the schedule you chose, for example Max 7 days for this schedule. See Look-back limits.

  8. Optional: in the Threshold panel, select Only fire when the result row count meets a threshold, then:

    1. In Operator, select > (greater than), >= (greater or equal), < (less than), <= (less or equal), or = (equal).

    2. In Value, enter the row count to compare against.

      See Threshold.

  9. Click Create.

The new scheduled search appears on the Scheduled Searches page with the status ACTIVE, and its first run happens at the next scheduled tick. To run it immediately, use Run now.

Write to an existing lookup table

  1. Under Lookup table, select Existing table.

  2. In Table name, select the lookup table to write to.

    The FuseQL query must return the same columns as the lookup table. For example, if the lookup table has the columns Timestamp, Message, and Source, the query must return those columns.

  3. Under Write mode, select how each run updates the table:

    • Merge - Upsert the results into the current contents of the table, matching rows by primary key.

    • Replace - Replace the current contents of the table completely.

Write to a new lookup table

  1. Under Lookup table, select New table.

  2. In New table name, enter a name for the lookup table, for example my_lookup_table.

  3. In Folder, select the folder to place the lookup table in, or click + New to create a folder.

  4. Under Columns from, define the table’s columns. Column names must match the columns that the scheduled search query returns.

    • Select Upload CSV, click Choose File, and select a CSV file of up to 100 rows. The first row is treated as the column headers.

    • Or select Define columns, then for each column:

      1. Enter the Column name.

      2. Select the column type: STRING, INT, LONG, FLOAT, DOUBLE, BIG_DECIMAL, BOOLEAN, TIMESTAMP, or JSON.

      3. Select Primary key if the column identifies a row. Merge uses the primary key to match rows.

        Click + Add column to add another column.

  5. Under Write mode, select Merge or Replace, as described in Write to an existing lookup table.

Custom cron expressions

A custom schedule uses a six-field cron expression, with seconds as the first field:

<second> <minute> <hour> <day-of-month> <month> <day-of-week>
Expression Schedule

0 */15 * * * *

Every 15 minutes

0 0 * * * *

Every hour, on the hour

0 30 2 * * *

Every day at 02:30 UTC

When you switch from Preset to Custom, the field is pre-filled with the cron expression for the preset you had selected.

Look-back limits

Each run queries the previous interval relative to now. The maximum look-back is restricted by how often the scheduled search runs, so that frequent schedules cannot query unbounded ranges of data. The look-back is validated when you save. For an irregular custom schedule, such as weekdays only, the period is the shortest gap between its runs.

Schedule period Maximum look-back

Every 15 minutes

1 day

More than 15 minutes, up to 1 hour

7 days

More than 1 hour, up to 3 hours

15 days

More than 3 hours, up to 12 hours

30 days

More than 12 hours

90 days

To look back further than the longest preset (Last 7 days), select Custom… and enter the look-back in seconds; for example, 2592000 for 30 days.

Threshold

The threshold is an optional row-count gate. When it is enabled, the notification fires only when the result row count meets the condition you specify. For example, set Operator to > (greater than) and Value to 50 to send an email only when the query returns more than 50 rows.

If the threshold is not met when the scheduled search runs, the run is marked SKIPPED: the notification does not fire, and the run appears with a SKIPPED status under Recent runs.

Manage scheduled searches

To open the list of scheduled searches, hover over Logs in the top navigation and select Scheduled Searches. Use the search box to filter by name, and the Status and Folder filters to narrow the list. Click Refresh to reload run results, and Columns to choose which columns are shown.

The list displays the following information for each scheduled search:

Column Description

Name

The name assigned when the scheduled search was created.

Folder

The folder the scheduled search is placed in.

Status

Whether the scheduled search is ACTIVE or PAUSED.

Query

The FuseQL query that runs at each tick.

Contact point

The email recipients or lookup table that receives the results. For a lookup table, the write mode (MERGE or REPLACE) is shown.

Schedule

How often the search runs, for example Every 6 hours or Daily at midnight.

Last run

The outcome and time of the most recent run.

Next run

When the search runs next, or — if it is paused.

Row actions

Click the … menu at the end of a row to act on that scheduled search:

Run now

Trigger a run immediately instead of waiting for the next scheduled tick. A manual run does not reset the schedule.

Pause / Resume

Stop or restart scheduled runs. An ACTIVE search shows Pause; a PAUSED search shows Resume. A paused search keeps its configuration and run history.

Edit

Open the Edit scheduled search page, which has the same panels as Create a Scheduled Search. Click Save changes to apply your changes.

View results

Open the results in the Logs Explorer in a new tab. Available only for scheduled searches that write to a lookup table.

Move to folder

Move the scheduled search to a different folder.

Copy query

Copy the FuseQL query to the clipboard.

Delete

Delete the scheduled search.

Scheduled search details

Click the name of a scheduled search to open its details panel on the right of the page. The buttons at the top of the panel run the same actions as the row menu: Run now, Pause or Resume, View results, Move, and Edit.

The panel shows:

  • Query - The full FuseQL query.

  • Contact point, Schedule (in both readable and cron form), Look-back, Threshold, and Folder.

  • Created by, Created at, Updated at, Last run, and Next run.

  • Next runs (local time) - The next three scheduled run times.

  • Recent runs - A table of recent runs with their Status, Started and Finished times, Rows returned, and any Message. An icon next to each status shows whether the run was triggered by the schedule or manually with Run now.

A run finishes with one of the following statuses:

  • SUCCESS - The run completed and the notification fired.

  • SKIPPED - The threshold was not met, so the notification did not fire.

  • FAILURE - The run did not complete. The Message column shows the returned error.

Click × in the top right of the panel to close it.