DOCSEARCHbyAlgolia
Submit Docs

TypeQL Query Language

repository·master·Indexed 42 days ago

https://github.com/typedb/typeql

A declarative, polymorphic query language for TypeDB based on the Polymorphic Entity-Relation-Attribute (PERA) model. TypeQL allows developers to define schemas using entities, relations, and attributes, and perform complex data operations through composable patterns, subtyping, and parametric queries.

Tokens
1.5K
Snippets
4
Records
7
Agent score
4%

What's inside TypeQL

  1. What is TypeQL?

    master

    TypeQL is the declarative, polymorphic query language for TypeDB. It is designed to be conceptual and intuitive, mirroring the TypeDB conceptual data model.

    Key characteristics include:

    • Declarative: You define query patterns (requirements) without specifying the execution strategy; TypeDB's query planner optimizes the execution.
    • Polymorphic: It supports the Polymorphic Entity-Relation-Attribute (PERA) model, allowing for powerful parametric database operations.
    • Composable: Complex queries are built by concatenating atomic constraints into patterns.
    • Variablizable: Any concept (entities, relations, attributes, or even types) can be variablized in a query.

  2. Status of the TypeQL Java library

    master

    The TypeQL Java library is currently deprecated following the release of TypeDB 3.0. New libraries featuring query builders and ORMs for the updated language version are currently under development.

    If your project requires the TypeQL 2.x library, you must use the specific legacy versions available in the releases section.

  3. Define types, inheritance, and interfaces in TypeQL

    master

    TypeQL uses a define block to establish the schema based on the PERA model. You can define attributes, entities, and relations, including subtyping (inheritance) and role interfaces.

    • Attributes: Properties with values (e.g., string).
    • Entities: Independent concepts that can own attributes and play roles in relations.
    • Relations: Connect entities or other relations via roles.
    • Subtyping: Use the sub keyword to create hierarchies (e.g., attribute email sub id).
    define
  attribute id value string;
  attribute email sub id;
  attribute path sub id;
  attribute name sub id;
  
  entity user,
    owns email @unique,
    plays permission:subject,
    plays request:requestee;
  entity file,
    owns path,
    plays permission:object;
  entity action,
    owns name,
    plays permission:action;
  
  relation permission,
    relates subject,
    relates object,
    relates action,
    plays request:target;
  relation request,
    relates target,
    relates requestee;

  4. Compose complex patterns in TypeQL

    master

    TypeQL patterns are fully composable. You can build complex queries by concatenating atomic constraints. Each constraint adds a requirement to the pattern match. For example, you can start with a general entity match and progressively add attribute requirements and relation constraints.

    # Simple match
match 
  $user isa user;

# Adding attribute constraints
match
  $user isa user;
  $user has email "john@typedb.com";

# Adding relation constraints
match
  $user isa user;
  $user has email "john@typedb.com";
  (team: $team, member: $user) isa team-membership;

# Adding further constraints to the related entity
match
  $user isa user;
  $user has email "john@typedb.com";
  (team: $team, member: $user) isa team-membership;
  $team has name "Engineering";

  5. Write polymorphic database queries

    master

    TypeQL allows you to query supertypes to automatically include all subtypes, and use variablized types to return the specific type of a concept.

    Querying a supertype

    To retrieve all entities of a specific type and its subtypes, use the isa keyword.

    Querying specific subtypes

    To filter for a more specific type within a hierarchy, use the subtype's name with isa.

    Returning types via variabilization

    You can variabilize a type itself to discover the specific type of an entity during a match.

    # This returns all users of any type
match 
  $user isa user,
    has full-name $name,
    has email $email;

# This returns only users who are employees
match 
  $user isa employee,
    has full-name $name,
    has email $email,
    has employee-id $id;

# This returns all users and their type
match 
  $user-type sub user;
  $user isa $user-type,
    has full-name $name,
    has email $email;

  6. Use TypeQL in TypeDB Drivers and Tools

    master
    All TypeDB Drivers and Tools (including the TypeDB Console) accept TypeQL syntax natively through strings. There is no requirement to install additional TypeQL libraries to execute queries.

  7. Perform data insertion and matching

    master

    TypeQL uses match to find existing data patterns and insert to create new entities and relations.

    match
  $kevin isa user, has email "kevin@typedb.com";
insert
  $chloe isa full-time-employee,
    has full-name "Chloé Dupond",
    has email "chloe@typedb.com",
    has employee-id 185,
    has weekly-hours 35;
  (employee: $chloe, ceo: $kevin) isa hiring,
    has date 2023-09-27;