# Table of Contents

- [CEL  |  Common Expression Language](#cel-common-expression-language)
- [Common Expression Language (CEL)](#common-expression-language-cel-)
- [Tutorials: Get started with CEL  |  Common Expression Language](#tutorials-get-started-with-cel-common-expression-language)
- [Sign in - Google Accounts](#sign-in-google-accounts)

---

# CEL  |  Common Expression Language

[Skip to main content](https://cel.dev/#main-content)

 [![Common Expression Language](https://www.gstatic.com/devrel-devsite/prod/v24b9c6b2afabba7cabce38ea39eb836b143c6716ce4ed7ad9b9ce1142f49221f/cel/images/lockup.svg)](https://cel.dev/)

/

*   [English](https://cel.dev/)
    
*   [Deutsch](https://cel.dev/?hl=de)
    
*   [Español – América Latina](https://cel.dev/?hl=es-419)
    
*   [Français](https://cel.dev/?hl=fr)
    
*   [Indonesia](https://cel.dev/?hl=id)
    
*   [Italiano](https://cel.dev/?hl=it)
    
*   [Polski](https://cel.dev/?hl=pl)
    
*   [Português – Brasil](https://cel.dev/?hl=pt-br)
    
*   [Tiếng Việt](https://cel.dev/?hl=vi)
    
*   [Türkçe](https://cel.dev/?hl=tr)
    
*   [Русский](https://cel.dev/?hl=ru)
    
*   [עברית](https://cel.dev/?hl=he)
    
*   [العربيّة](https://cel.dev/?hl=ar)
    
*   [فارسی](https://cel.dev/?hl=fa)
    
*   [हिंदी](https://cel.dev/?hl=hi)
    
*   [বাংলা](https://cel.dev/?hl=bn)
    
*   [ภาษาไทย](https://cel.dev/?hl=th)
    
*   [中文 – 简体](https://cel.dev/?hl=zh-cn)
    
*   [中文 – 繁體](https://cel.dev/?hl=zh-tw)
    
*   [日本語](https://cel.dev/?hl=ja)
    
*   [한국어](https://cel.dev/?hl=ko)
    

[Sign in](https://cel.dev/_d/signin?continue=https%3A%2F%2Fcel.dev%2F&prompt=select_account)

*   [CEL](https://cel.dev/)
    

    // Simple predicates
    'tacocat'.startsWith('taco')
    
    // Parameterized predicates over structured data
    account.balance >= transaction.withdrawal
    
    // JSON objects
    {'sub': '12345678',
     'aud': 'example2.cel.dev',
     'iss': 'https://example1.cel.dev/jwt-issuer'}
    
    // Strongly typed objects
    common.GeoPoint{ latitude: 10.0, longitude: -5.5 }

### Fast, safe expression language

Common Expression Language (CEL) is an expression language that’s fast, portable, and safe to execute in performance-critical applications. CEL is designed to be embedded in an application, with application-specific extensions, and is ideal for extending declarative configurations that your applications might already use.

Use CEL for things like list filters for API calls, validation constraints on protocol buffers, and authorization rules for API requests.

[Learn more](https://cel.dev/overview/cel-overview)
 [Get started](https://cel.dev/tutorials/cel-get-started-tutorial)

speed

### Fast

Accelerated expression evaluation in performance-critical paths from nanoseconds to microseconds.

language

### Portable

Developer friendly, light weight with common syntax across multiple Google and external systems.

hub

### Extensible

Supports subsetting and extension, easy to embed and tailor to configuration and policy requirements.

verified\_user

### Safe

Non-Turing complete, and only accesses data provided by the host application.

![](https://cel.dev/static/images/cel-assess_2880.png)

### Is CEL right for your project?

CEL is ideal for performance-critical applications because it was designed to evaluate safely and quickly (nanoseconds to microseconds) with predictible costs. CEL expressions are especially useful for predicate logic and simple data transformations.

CEL is used most efficiently in applications where expressions are evaluated frequently, but modified infrequently. For example, evaluating an HTTP request against a security policy is an excellent use case for CEL. A CEL security policy expression would have a one-time configuration cost for validating the expression and then be evaluated very frequently at a negligible cost.

Still not sure? Check out the CEL overview and language definition, or just ask us! We're happy to help.

[CEL overview](https://cel.dev/overview/cel-overview)
 [Language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md)
 [Ask our team](https://mail.google.com/mail/u/0/?fs=1&tf=cm&to=cel-lang-discuss@googlegroups.com&su=[cel-lang-discuss]%20Question%20for%20the%20CEL%20team&body=Greetings,%20CEL%20team!%20I%20have%20the%20following%20question:%0A%0A)

### [Contribute to CEL](https://github.com/google/cel-spec/blob/master/CONTRIBUTING.md)

Want to help the CEL project? Contribute to our open source code and documentation. We'd love your help!

[Contribute](https://github.com/google/cel-spec/blob/master/CONTRIBUTING.md)

---

# Common Expression Language (CEL)

[Skip to main content](https://cel.dev/overview/cel-overview#main-content)

 [![Common Expression Language](https://www.gstatic.com/devrel-devsite/prod/v24b9c6b2afabba7cabce38ea39eb836b143c6716ce4ed7ad9b9ce1142f49221f/cel/images/lockup.svg)](https://cel.dev/)

/

*   [English](https://cel.dev/overview/cel-overview)
    
*   [Deutsch](https://cel.dev/overview/cel-overview?hl=de)
    
*   [Español – América Latina](https://cel.dev/overview/cel-overview?hl=es-419)
    
*   [Français](https://cel.dev/overview/cel-overview?hl=fr)
    
*   [Indonesia](https://cel.dev/overview/cel-overview?hl=id)
    
*   [Italiano](https://cel.dev/overview/cel-overview?hl=it)
    
*   [Polski](https://cel.dev/overview/cel-overview?hl=pl)
    
*   [Português – Brasil](https://cel.dev/overview/cel-overview?hl=pt-br)
    
*   [Tiếng Việt](https://cel.dev/overview/cel-overview?hl=vi)
    
*   [Türkçe](https://cel.dev/overview/cel-overview?hl=tr)
    
*   [Русский](https://cel.dev/overview/cel-overview?hl=ru)
    
*   [עברית](https://cel.dev/overview/cel-overview?hl=he)
    
*   [العربيّة](https://cel.dev/overview/cel-overview?hl=ar)
    
*   [فارسی](https://cel.dev/overview/cel-overview?hl=fa)
    
*   [हिंदी](https://cel.dev/overview/cel-overview?hl=hi)
    
*   [বাংলা](https://cel.dev/overview/cel-overview?hl=bn)
    
*   [ภาษาไทย](https://cel.dev/overview/cel-overview?hl=th)
    
*   [中文 – 简体](https://cel.dev/overview/cel-overview?hl=zh-cn)
    
*   [中文 – 繁體](https://cel.dev/overview/cel-overview?hl=zh-tw)
    
*   [日本語](https://cel.dev/overview/cel-overview?hl=ja)
    
*   [한국어](https://cel.dev/overview/cel-overview?hl=ko)
    

[Sign in](https://cel.dev/_d/signin?continue=https%3A%2F%2Fcel.dev%2Foverview%2Fcel-overview&prompt=select_account)

*   [About CEL](https://cel.dev/overview/cel-overview)

*   On this page
*   [Why CEL?](https://cel.dev/overview/cel-overview#why_cel)
    
*   [Core concepts of CEL](https://cel.dev/overview/cel-overview#core_concepts_of_cel)
    *   [Expressions](https://cel.dev/overview/cel-overview#expressions)
        
    *   [Environments](https://cel.dev/overview/cel-overview#environments)
        
    *   [Phases of expression processing](https://cel.dev/overview/cel-overview#phases_of_expression_processing)
        
*   [Related resources](https://cel.dev/overview/cel-overview#related_resources)
    

*   [CEL](https://cel.dev/)
    
*   [Overview](https://cel.dev/overview/cel-overview)
    

Was this helpful?

Common Expression Language (CEL)
================================

*   On this page
*   [Why CEL?](https://cel.dev/overview/cel-overview#why_cel)
    
*   [Core concepts of CEL](https://cel.dev/overview/cel-overview#core_concepts_of_cel)
    *   [Expressions](https://cel.dev/overview/cel-overview#expressions)
        
    *   [Environments](https://cel.dev/overview/cel-overview#environments)
        
    *   [Phases of expression processing](https://cel.dev/overview/cel-overview#phases_of_expression_processing)
        
*   [Related resources](https://cel.dev/overview/cel-overview#related_resources)
    

Common Expression Language (CEL) is a general-purpose expression language designed to be fast, portable, and safe to execute. You can use CEL on its own or embed it into a larger product. CEL is a great fit for a wide variety applications, from routing remote procedure calls (RPCs) to defining security policies. CEL is extensible, platform independent, and optimized for compile-once/evaluate-many workflows.

CEL was designed specifically to be safe for executing user code. While it's dangerous to blindly call `eval()` on a user's python code, you can safely execute a user's CEL code. And because CEL prevents behavior that would make it less performant, it evaluates safely in nanoseconds or microseconds. The speed and safety of CEL makes it ideal for performance-critical applications.

CEL evaluates expressions that are similar to single-line functions or lambda expressions. While CEL is commonly used for boolean decisions, you can also use it to construct more complex objects like JSON or protocol buffer messages.

Why CEL?
--------

Many services and applications evaluate declarative configurations. For example, role-based access control (RBAC) is a declarative configuration that produces an access decision given a user role and a set of users. While declarative configs are sufficient for most cases, sometimes you need more expressive power. That's where CEL comes in.

As an example of extending a declarative config with CEL, consider the capabilities of Google Cloud [Identity and Access Management (IAM)](https://cloud.google.com/iam)
. While RBAC is the common case, IAM offers CEL expressions to allow users to further constrain the scope of the role-based grant according to the proto message properties of the request or the resources being accessed. Describing such conditions through the data model would result in a complicated API surface that's difficult to work with. Instead, using CEL with attribute-based access control (ABAC) is an expressive and powerful extension to RBAC.

Core concepts of CEL
--------------------

In CEL, an expression is compiled against an environment. The compilation step produces an abstract syntax tree (AST) in [protocol buffer](https://protobuf.dev/)
 format. Compiled expressions are stored for future use to keep the evaluation as fast as possible. A single compiled expression can be evaluated with many different inputs.

Here's a closer look at some of these concepts.

### Expressions

**Expressions are written by users.** Expressions are similar to single-line function bodies or lambda expressions. The function signature that declares the input is written outside of the CEL expression, and the library of functions available to CEL is auto-imported.

For example, the following CEL expression takes a request object, and the request includes a `claims` token. The expression returns a boolean value that indicates whether the `claims` token is still valid.

_Example CEL expression to authenticate a claims token_

// Check whether a JSON Web Token has expired by inspecting the 'exp' claim.
    //
    // Args:
    //   claims - authentication claims.
    //   now    - timestamp indicating the current system time.
    // Returns: true if the token has expired.
    //
    timestamp(claims["exp"]) < now

While users define the CEL expression, services and applications define the environment where it runs.

### Environments

**Environments are defined by services**. Services and applications that embed CEL declare the expression environment. The environment is the collection of variables and functions that can be used in CEL expressions.

For example, the following `textproto` code declares an environment containing the `request` and `now` variables using the `CompileRequest` message from a CEL service.

_Example CEL environment declaration_

# Format: $SOURCE_PATH/service.proto#CompileRequest
    declarations {
      name: "request"
      ident {
        type { message_type: "google.rpc.context.AttributeContext.Request" }
      }
    }
    declarations {
      name: "now"
      ident {
        type { well_known: "TIMESTAMP" }
      }
    }

The proto-based declarations are used by the CEL type-checker to ensure that all identifier and function references within an expression are declared and used correctly.

### Phases of expression processing

CEL expressions are processed in three phases:

1.  Parse
2.  Check
3.  Evaluate

The most common pattern of CEL usage is to parse and check expressions at config time, store the AST, and then retrieve and evaluate the AST repeatedly at runtime.

_Illustration of CEL processing phases_

![Expressions are parsed and checked on configuration paths, stored, and then\
evaluated against one or more contexts on read paths.](https://cel.dev/static/images/cel-flow.png)

CEL is parsed from a human-readable expression to an AST using an [ANTLR](https://www.antlr.org/)
 lexer and parser grammar. The parse phase emits a proto-based AST where each `Expr` node in the AST contains an integer ID that's used to index into metadata generated during parsing and checking. The [`syntax.proto`](https://github.com/googleapis/googleapis/blob/master/google/api/expr/v1alpha1/syntax.proto)
 file that's produced during parsing represents the abstract representation of what was typed in the string form of the expression.

After an expression is parsed, it's then type-checked against the environment to ensure all variable and function identifiers in the expression have been declared and are being used correctly. The type-checker produces a [`checked.proto`](https://github.com/googleapis/googleapis/blob/master/google/api/expr/v1alpha1/checked.proto)
 file that includes type, variable, and function resolution metadata that can drastically improve evaluation efficiency.

Finally, after an expression is parsed and checked, the stored AST is evaluated.

The CEL evaluator needs three things:

*   Function bindings for any custom extensions
*   Variable bindings
*   An AST to evaluate

The function and variable bindings should match what was used to compile the AST. Any of these inputs can be reused across multiple evaluations, such as an AST being evaluated across many sets of variable bindings, the same variables used against many ASTs, or the function bindings used across the lifetime of a process (a common case).

Related resources
-----------------

*   [CEL tutorial](https://cel.dev/tutorials/cel-get-started-tutorial)
    
*   [Language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md)
    
*   [Function reference guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#list-of-standard-definitions)
    

Was this helpful?

Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/)
, and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0)
. For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies)
. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2023-11-06 UTC.

---

# Tutorials: Get started with CEL  |  Common Expression Language

[Skip to main content](https://cel.dev/tutorials/cel-get-started-tutorial#main-content)

 [![Common Expression Language](https://www.gstatic.com/devrel-devsite/prod/v24b9c6b2afabba7cabce38ea39eb836b143c6716ce4ed7ad9b9ce1142f49221f/cel/images/lockup.svg)](https://cel.dev/)

/

[Sign in](https://cel.dev/_d/signin?continue=https%3A%2F%2Fcel.dev%2Ftutorials%2Fcel-get-started-tutorial&prompt=select_account)

*   [Get started with CEL](https://cel.dev/tutorials/cel-get-started-tutorial)

*   [CEL](https://cel.dev/)
    
*   [Learn](https://cel.dev/tutorials/cel-get-started-tutorial)
    

Was this helpful?

Tutorials: Get started with CEL
===============================

To get started with CEL, choose from the following tutorials:

*   [CEL-Java codelab](https://github.com/google/cel-java/tree/main/codelab)
    
*   [CEL-C++ codelab](https://github.com/google/cel-cpp/tree/master/codelab)
    
*   [CEL-Go codelab](https://codelabs.developers.google.com/codelabs/cel-go#0)
    

Was this helpful?

Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/)
, and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0)
. For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies)
. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-01-26 UTC.

---

# Sign in - Google Accounts

Sign in with Google

Sign in
=======

to continue to Google Developer Docs

Email or phone

Forgot email?

Type the text you hear or see

Before using this app, you can review Google Developer Docs’s [privacy policy](https://google.com/policies/privacy)
 and [terms of service](https://google.com/policies/terms)
.

Next

Create account

---