Sign inTry Free

Important

Helios features are now enabled during weekly update windows and are no longer directly tied to SingleStore engine releases. Refer to the release notes to view the latest features available in your Helios cluster.

Scheduled Jobs

On this page

A scheduled execution of a notebook is referred to as a “job.” The SingleStore job service provides a flexible and convenient way to schedule jobs using cron expressions that can be tailored to meet your requirements. Cron-based scheduling uses the standard cron syntax, providing precise control over when workloads are run. It supports the format - minute hour day month weekday, and allows for complex scheduling patterns (e.g., running jobs at 8:00 AM every Monday). Create, edit, and delete cron schedules, and validate cron expressions in real time.

After scheduling, the job service creates a snapshot. This snapshot represents a read-only notebook captured at the time the job was scheduled. It can be used for subsequent executions at the scheduled time until the user makes modifications. To ensure that the execution reflects the new changes, be sure to update the snapshot explicitly after modifying the notebook.

Create and manage scheduled jobs using the Cloud Portal or via the Management API.

Scheduled Jobs using the Cloud Portal

Create a Scheduled Job

Jobs can be scheduled for shared notebooks only. Create a scheduled job using the one of the following methods:

  1. Navigate to Jobs in the left navigation and select Schedule (on the top right).

  2. Navigate to Editor > Shared.

    1. Select a shared notebook.

    2. Select Schedule (on the top right).

New Scheduled Job

After selecting Schedule, enter or select the following in Job Settings.

Job Settings

Name

Enter a name for the job.

Description

Enter the job description.

Notebook

Select a shared notebook to run the job. The shared notebook is pre-selected when Job is scheduled through notebooks.

Cluster

Select the SingleStore cluster the notebook connects to.

Selecting a cluster allows connecting the SingleStore databases referenced in the notebook natively. A scheduled job can also be run without a cluster attached to it.

Runtime

Select a runtime from the following:

  • Small

  • Medium

  • GPU-T4

Note

This field is in preview.

Region

Select a region.

Select Next. Enter the Schedule Options.

Scheduled Options

Start Executions After

Specify the date and time for the first run of the scheduled job. Select one of the following available options:

  1. Now: The job runs as soon as it is created.

  2. Datetime: Specify a Starting Date and Starting Time.

Schedule Mode

Specify the frequency to run a scheduled job. Select one of the following available options:

  1. One Time: The job runs a single time.

  2. Recurring: Specify when the job needs to be run. Select from the following:

    • Hourly

    • Weekly

    • Monthly

    • Weekdays at 9 PM

    • Every 6 Hours

    • Enter a custom valid CRON expression.

Parameters

Specify the job parameters for the scheduled job. 

  1. Type: Select the type of parameters from the following:

    • String

    • Integer

    • Float

    • Boolean

  2. Name: Enter the name of the parameter.

  3. Value: Enter the value of the parameter.

Note

The system injects parameters as Python variables into the notebook while the scheduled job runs, and access them using the variables where required.

Additional Settings

  1. Save all execution results: Enable this setting to save the execution results. An execution result is a saved version of the notebook along with the cells containing outputs after the completion of a job run. This action enables to validate the execution result and the version of the notebook used for the run. By default, all snapshots for error and failed runs are saved.

  2. Auto resume the cluster on job execution: Enable this setting to resume the cluster when the job runs. This action resumes any suspended clusters. The previous auto-suspend settings of the clusters remain unchanged.

Select Next, review the Summary, and then select Create Job to schedule the job.

Access Control for Scheduled Jobs

Recurring Scheduled Jobs are governed by the Container Services RBAC model. Each recurring Scheduled Job is backed by an Aura App resource, and access is controlled through Aura App roles.

Scope: Access Control for Scheduled Jobs only applies to recurring jobs. One-time jobs are not currently governed by the Aura App RBAC model.

Who Can Create a Scheduled Job

Creating a recurring Scheduled Job requires an organization-level role that grants the Aura Apps create permission (for example, the Aura Creator role). Organization members without this permission cannot create recurring Scheduled Jobs.

When a user creates a recurring Scheduled Job, the system automatically grants that user the Owner role on the new job.

Roles and Permissions

Role

Permissions

Owner

  • Use (view)

  • Update (edit)

  • Pause

  • Resume

  • Delete

  • Share (Control Access)

User

  • Use (view)

Visibility

Users can only view the recurring Scheduled Jobs for which they have Owner or User access. Jobs without an explicit role grant do not appear in the Jobs page or in Management API responses.

Aura App roles are granted per job by default. Each recurring Scheduled Job has its own Owner and User role assignments. To access multiple jobs, a user must be granted the Owner or User role on each job individually, receive access through a team, or inherit access from an organization-level role that covers all Aura App resources. Refer to Organization Role Inheritance more information. Users without a required role on a specific job cannot view that job. Operators also cannot view all jobs by default unless they have an explicit grant.

Organization Role Inheritance

The following organization roles automatically inherit full Owner permissions on all recurring Scheduled Jobs in the organization:

  • Organization Owner

  • AI Administrator

Other organization roles (Reader, Writer, Operator, Observer, Billing Administrator, and User Administrator) do not inherit Scheduled Job access. Users with these roles need an explicit Owner or User grant on a specific recurring job to view or manage it.

Refer to Container Services RBAC for more information.

Share Access to a Scheduled Job

Owners can share a recurring Scheduled Job with other users or teams from the job's action menu.

  1. Navigate to Jobs in the left navigation.

  2. Select the ellipsis (three dots) in the Actions column of the target job.

  3. Select Share.

  4. Select the user or team, assign the Owner or User role, and select Save.

To remove access, select Remove Access for the user or team.

Guarded Actions

Action

Required Role

View / List

Owner or User

Edit Job

Owner

Pause

Owner

Resume

Owner

Delete

Owner

Share / Manage Access

Owner

Manage an Existing Job

Note

You can manage a recurring Scheduled Job only if you have the Owner role on it. Users with the User role can view the job and its runs but cannot edit, pause, resume, delete, or share it. This behavior applies to recurring jobs only. Refer to Access Control for Scheduled Jobs for more information.

To view an existing scheduled jobs and job runs, select Jobs in the left navigation pane. Existing jobs can be managed by performing the following actions:

  • View

  • Edit

  • Pause

  • Resume

  • Delete

View an Existing Job

To view a job, select the job name under the Name column and view the job execution details for each job.

View the details of a job on the Job Details pane in the right navigation. This page also supports refresh, edit, pause, resume, and delete actions for a job.

Edit an Existing Job

To edit an existing job, navigate to the selected job page, select the ellipsis, and select Edit Job.

Pause an Existing Job

To pause an existing job, navigate to the Jobs page, select the ellipses in the Actions column of the job, and select Pause. Alternatively, navigate to the selected job page, and select Pause Job.

Resume an Existing Job

To resume an existing job, navigate to the Jobs page, select the ellipses in the Actions column of the job, and select Resume.

Delete an Existing Job

To delete an existing job, navigate to the Jobs page, select the ellipses in the Actions column of the job, and select Delete.

Warning

Deleting a job removes all associated job runs, including snapshots.

Schedule Jobs using the Management API

Use the Jobs path (/v1/jobs endpoint) to create and manage jobs using the Management API. Refer to Management API and Management API Reference for more information.

For example, the following API call returns information about the job with the specified jobID:

curl -X 'GET' \ 'https://api.singlestore.com/v1/jobs/7b68b78d-a000-4000-9000-0864fd331524' \ -H 'accept: application/json'

Status of Job Executions

Status

Description

Scheduled

The next scheduled run for the job. The latest version of the notebook runs at the Start Time associated with the job.

Completed

The notebook in this job run ran to completion.

Failed

The execution failed due to user error. View execution result to debug the failure.

Error

An error unrelated to the notebook code prevented this job from completing. Refer to Troubleshoot Job Runs.

Troubleshoot Job Runs

SingleStore automatically saves an execution result notebook of an execution that fails. Navigate to Jobs in the left navigation, find the job, and download the snapshot associated with the failed job run to diagnose the error.

Error

Solution

Cluster Deleted

Edit the Job and select a cluster.

Cluster Suspended

Resume the cluster, or create a new scheduled job with a different cluster.

Database Detached

Reattach the database with the right permissions or create a new scheduled job with a different database.

Internal Errors / Misc

Reach out to SingleStore Support or use the chat feature in the Cloud Portal.

Notebook Timed Out

View the snapshot to identify the cells where the notebook is timed out.

Refer to Configurability and Key Considerations for the Execution Time limits set on a job run.

Notebook Deleted/Not present

Create a new scheduled job with a different notebook.

Configurability and Key Considerations

Scheduled notebook jobs run using a snapshot of the notebook captured at the time the job is created or last refreshed. Updates made to the notebook after the snapshot is captured do not affect scheduled job runs.

To apply updates to a scheduled job, explicitly refresh the notebook snapshot. In the Jobs page, select the job and then select Refresh in the top right. Alternatively, select the ellipsis (three dots), select Edit Job, and enable Update snapshot to reflect the updates from the associated notebook in the job.

An execution time limit is set for each job:

  • Maximum allowed execution duration: Specifies the maximum total time a notebook job can run, including all retries. The job is terminated when this limit is reached, even if execution is still in progress. The maximum allowed execution duration limit is 8 hours.

  • Minimum execution interval: Specifies the minimum required time interval between consecutive notebook job runs. Schedules with intervals shorter than this limit are not allowed. The minimum execution interval limit is 60 minutes.

  • Maximum execution interval: Specifies the maximum allowed time between consecutive notebook job runs. Schedules with intervals longer than this limit are not allowed. The maximum execution interval limit is 31 days.

Examples

The following examples demonstrate how maximum allowed execution duration, minimum execution interval, and maximum execution interval are used while creating a scheduled job and how those patterns apply to scheduling notebooks within the SingleStore job service.

Example 1: Hourly Data Refresh Job

Run a notebook every hour to refresh business analytics tables.

Configuration

Cron Expression: 0 * * * *

Execution Time Limits

Execution Time Parameter

Value

Minimum execution interval

60 minutes

Maximum execution interval

31 days

Maximum allowed execution duration

8 hours
Behavior

This configuration allows the notebook to run once every hour, which satisfies the minimum execution interval of 60 minutes and remains within the maximum execution interval of 31 days. Each job run can execute for up to 8 hours, including retries, after which the system terminates the running job automatically. Cron expressions that schedule executions more frequently than once per hour, such as */30 * * * * are not allowed.

Example 2: Monthly Compliance Report

Run a notebook once per month to generate a compliance report.

Configuration

Cron Expression: 0 0 1 * *

Execution Time Limits

Execution Time Parameter

Value

Minimum execution interval

60 minutes

Maximum execution interval

31 days

Maximum allowed execution duration

8 hours
Behavior

This configuration allows the notebook to run approximately once every 31 days, which satisfies both the minimum execution interval of 60 minutes and the maximum execution interval of 31 days. Each execution is limited to 8 hours, including retries, and the system terminates the running job if it exceeds this duration. Cron expressions that schedule executions less frequently than once every 31 days, such as 0 0 1 1 * are not allowed.

Last modified:

Was this article helpful?

On this page

Was this article helpful?

Verification instructions

Note: You must install cosign to verify the authenticity of the SingleStore file.

Use the following steps to verify the authenticity of singlestoredb-server, singlestoredb-toolbox, singlestoredb-studio, and singlestore-client SingleStore files that have been downloaded.

You may perform the following steps on any computer that can run cosign, such as the main deployment host of the cluster.

  1. (Optional) Run the following command to view the associated signature files.

    curl undefined

  2. Download the signature file from the SingleStore release server.

    • Option 1: Click the Download Signature button next to the SingleStore file.

    • Option 2: Copy and paste the following URL into the address bar of your browser and save the signature file.

    • Option 3: Run the following command to download the signature file.

      curl -O undefined

  3. After the signature file has been downloaded, run the following command to verify the authenticity of the SingleStore file.

    echo -n undefined |
        cosign verify-blob --certificate-oidc-issuer https://oidc.eks.us-east-1.amazonaws.com/id/CCDCDBA1379A5596AB5B2E46DCA385BC \
          --certificate-identity https://kubernetes.io/namespaces/freya-production/serviceaccounts/job-worker \
          --bundle undefined \
          --new-bundle-format -
    Verified OK

Try Out This Notebook to See What’s Possible in SingleStore

Get access to other groundbreaking datasets and engage with our community for expert advice.

Sign UpLog In