Categories:

Data metric functions

FRESHNESS (system data metric function)

Returns the difference in seconds between the maximum value of a timestamp column and the scheduled time when the data metric function runs.

Syntax

SNOWFLAKE.CORE.FRESHNESS(<query>)
Copy

Arguments

query

Specifies a SQL query on a table or view.

Allowed data types

The referenced columns in the query must have either of the following data types:

  • DATE

  • TIMESTAMP_LTZ

  • TIMESTAMP_TZ

Returns

The function returns a scalar value with a NUMBER data type.

Access control requirements

To use a system DMF, choose one of the following access control approaches:

  • Grant the DATA_METRIC_USER database role to the table owner role, which is the role with the OWNERSHIP privilege on the table. This database role has the USAGE privilege on the SNOWFLAKE.CORE schema and the USAGE privilege on all system DMFs in the SNOWFLAKE.CORE schema.

    Additionally, grant the privileges in this table to the table owner role:

    Privilege

    Object

    Notes

    EXECUTE DATA METRIC FUNCTION

    Account

    This privilege enables you to control which roles have access to serverless compute resources to call the system DMF.

    USAGE

    Database, schema

    These objects are the database and schema that contain the referenced table in the query.

  • Grant the privileges in the table to the table owner role and grant these privileges to the table owner role:

  • Use the ACCOUNTADMIN role.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

Example

Determine the freshness of the data, 300 seconds or 5 minutes, in the table by measuring the TIMESTAMP column:

SELECT SNOWFLAKE.CORE.FRESHNESS(
  SELECT
    timestamp
  FROM hr.tables.empl_info
) < 300;
Copy
+---------------------------------------------------------------------+
| SNOWFLAKE.CORE.FRESHNESS(SELECT timestamp FROM hr.tables.empl_info) |
+---------------------------------------------------------------------+
| True                                                                |
+---------------------------------------------------------------------+
Language: English