Skip to main content

Hypi Directives

A directive allows you to customise the behaviour of your data model. Hypi's built-in directives allow you to tell Hypi how to interact with your fields. For example, if you want to have some customisation like checking the lengths of String or Array fields or applying past and future date settings, you may do so using the directives provided by Hypi.

What is a directive#

An @ character followed by a series of characters identifies a directive. It is optionally followed by a list of named arguments, which can appear after almost any form of syntax in the GraphQL query or schema languages.

strl: String @length(min: 1, max: 5)

Here, @length is the directive applied on the string field strl. min and max are the arguments that set the conditions to execute the directive.

Below is the schema built using some of the built-in directives.

type Message {
//@length directive
strl: String @length(min: 3, max: 5)
strl1: String @length(min: 1, max: 5)
strl2: String @length(min: 1, max: 5)
args: [String] @length(min: 1, max: 5)
//@notEmpty directive
notEmpty: String @notEmpty
//@uniqueVal directive
uniqueVal: String @unique
//@past and @future directive
past: DateTime @past
future: DateTime @future
//@pattern directive
pattern: String @pattern(regex: ["^test.*$"])
pattern1: String @pattern(regex: ["^test.*$", "^pass.*$"],
allMustMatch: true)
pattern2: String @pattern(regex: ["^test.*$", "^pass.*$"],
allMustMatch: false)
//@email directive
email: String @email
email1: String @email
email2: String @email
//@indices directive
type CheckIndex @indices(sets:[
["name"],
["age","id"]
]){
name: String
age: Int
id: Int
}
//@secret directive
sha: String @secret(hash: SHA3) #adslkjkjwdksjcfjskdjh
bcrypt: String @secret(hash: BCRYPT) #lkdfjfeijewkllkjwekjf
#hello world => dlfjdlkjfejlsldkjfkldnmksjklfjkewjnfk
#dlfjdlkjfejlsldkjfkldnmksjklfjkewjnfk => hello world
pkcs5: String @secret(hash: PKCS5)
}
type Post {
//@computed directive
title: String
postCreated: DateTime @computed(query: "hypi.id = '${self.hypi.id}'",
type: "Post", postQueryFn: "res[0].hypi.created")
augmentedTitle: String @computed(postQueryFn:
"""self.title + " computed" """)
date: DateTime @computed(postQueryFn:
"import java.time.ZonedDateTime; return ZonedDateTime.now()")
combine: String @computed(postQueryFn:
"""self.hypi.id + ":" + self.title """)
}
//Directives to stop generation of tables
type AWithNoDirs @noagg @notable @noinput @nomath {
f1: String
}

Built-in directives#

Let’s look at Hypi's built-in directives one by one. You may refer to the schema above for reference. The examples given for using the directives are self-explanatory. You may disable a directive by adding # in front of it.

@length#

This directive is valid on String, Object and, Array fields. You may check if the string length or array length matches the range. You may also check if the object's list of non-null fields matches the range. But it doesn’t validate existing data. It just validates the length. It returns an error if the string length or an array length goes beyond specified limits.

strl: String@length(min: 3, max: 5)

note

A whitespace also gets added as an additional character while calculating the length of the string.

mutation {
upsert(values: {
Message: {
strl:"12",
strl1:"123456",
strl2:" ",
args:["1","2","3","4","5","6"]
}
}
) {
id
}
}

@notEmpty#

This directive returns an error message if the string or an array is empty or null. It also returns an error even if the string just has whitespaces.

notEmpty: String @notEmpty

mutation {
upsert(values: {
Message: {
notEmpty:" "
}
}
) {
id
}
}

@unique#

Adding this directive to any keyword indexed field ensures that no duplicates can be inserted for that field. For example, let’s say the value 1 has been added for a field uniqueVal while creating an object. While creating another object, again upserting the same value in the same field would result in an error.

uniqueVal: String@unique

mutation {
upsert(values: {
Message: {
uniqueVal:"1"
}
}
) {
id
}
}

@past#

This directive checks if a date specified in a ‘DateTime’ field is a past date. If it is not, it returns an error. The format accepted by the field is ISO 8601 standard – UTC date format.

@future#

This directive checks if a date specified in a ‘DateTime’ field is a future date. If it is not, it returns an error. Te format accepted by the field is ISO 8601 standard – UTC date format.

past: DateTime@past

future: DateTime@future

Example of @past and @future directives:

mutation {
upsert(values: {
Message: {
past:"2021-08-12T04:19:02Z",
future:"2021-03-12T04:19:02Z"
}
}
) {
id
}
}

@pattern#

This directive checks if the field's value matches the given regular expression (regex). It takes regex values within brackets as an input. There is another Boolean parameter allMustMatch that defaults to false. If it is ‘true’ it means the value in the field must match both the regular expressions in the bracket (AND condition). If it is false, the field value may match with any of the two expressions(OR condition).

pattern: String @pattern(regex: ["^test.*$"])

Check the guideline for framing Regex: https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html

mutation {
upsert(values: {
Message: {
pattern:"alpha",
pattern1:"beta",
pattern2:"gamma"
}
}
) {
id
}
}

@email#

This directive checks if the field's value is a valid email address.

email: String @email

mutation {
upsert(values: {
Message: {
email:"abc",
email1:"abc@xyz"
email2:"abc@xyz.com"
}
}
) {
id
}
}

@computed#

This directive allows the value of a field to be calculated using an ArcQL query. You may also use a groovy-like function to combine the values in the fields. You may combine string or date values to match your requirements.

combine: String@computed(postQueryFn: """self.hypi.id + ":" + self.title """)

{
find(type: Post, arcql: "*") {
edges {
node {
... on Post {
title
postCreated
augmentedTitle
date
combine
}
}
cursor
}
}
}

@noinput / @nomath / @noaggs / @nomath#

Hypi automatically generates certain data types when you declare a type. These generated types are used to implement functionalities like CRUD, Aggregations, Maths functions, etc.

Let’s say you declared the following data type.

type AWithNoDirs {
f1: String
}

When you save the schema, the following tables will be automatically generated.

AWithNoDirs
AWithNoDirsInputOpt
AWithNoDirsAggs
AWithNoDirsGroupByOptions
AWithNoDirsInput
HypiUpsertInputUnion.AWithNoDirs: [AWithNoDirsInputOpt!]

You may check the details of these types under the documentation on the Hypi platform.

Now, declare the same data type like this:

type AWithNoDirs @noagg @notable @noinput @nomath {
f1: String
}

When you save the above data type, only the AWithNoDirs table will get generated. Other tables will not be generated and the user will not be able to perform associated functions.

@noinput tells Hypi not to generate an input type for this type. This prevents objects of this type from being used in upsert and other functions. So, you will not be able to perform mutations on this data type.

@notable tells Hypi not to generate a table for the type it is attached to (AWithNoDirs here). Instead, the user will use a serverless function or some other method to produce objects of this type. So, you will not be able to create objects of this type.

@noagg tells Hypi not to generate aggregation fields for the type it is attached to. So you will not be able to perform aggregation functions on AWithNoDirs

@nomath tells Hypi not to generate Maths fields for the type it is attached to. So you will not be able to perform Mathematical functions on AWithNoDirs

@http#

When this directive is applied, the value of the applied field gets resolved using an HTTP query configured with the given parameters. (See more about @http directive here)

@tan#

This directive is used to implement serverless functions. (See more about @tan directive here)

@indices#

In relational databases like SQL server, Oracle, MySQL or Postgres, you can create a data structure in the database that allows it to perform query on your fields in a performant way. So if you know that you won’t be able to query your data using hypi.id then it is a good idea to create an index on the fields that you will use to query - otherwise your queries will get slower and slower as the amount of data grows.

In the following example, an index is created on thepath  field because it will be used for queries instead ofhypi.id. 

You can create one or more indices on one or more fields.

@indices (sets: [
["path"],
["host","port"]
])

This example create two indices, one on path and a composite index on both host and port. It allows performant queries on path by itself i.e. path = '/abc' or on the host and port host = 'hypi.io' AND port > 79

In the CheckIndex data type declared in the schema, name and [age,id] are the indices. You may query the data using the 'find' function with arql query. The query will remain the same, but performance will be maintained as the data grows.

{
find(type: CheckIndex, arcql: "age = 17 AND id = 1") {
edges {
node {
... on CheckIndex {
name
age
id
}
}
cursor
}
}
}

@secret#

Fields annotated with the@secretdirective are encrypted using one of the three algorithms.

  1. SHA3
  2. BCRYPT
  3. PKCS5.

Hence, the values of these fields do not remain in a human-readable format. Out of the three algorithms, the encrypted values of SHA3 and BCRYPT can never be retrieved back. You can only run queries if the values match. These encryptions are good for password fields. However, PKCS5 values may be decrypted when necessary.

sha: String@secret(hash: SHA3)

@deprecated#

Deprecated fields on a type or Enum values can be marked as deprecated in the Schema using the @deprecated directive. A reason for deprecation has to be included. The reason is formatted using Markdown syntax.

directive @deprecated(
reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE

In the below example, the someTest field has been marked as deprecated. If you use the field within a query in the GraphQL editor, it highlights the field with a popped up message with the reason for deprecation.

type checkSkip{
someTest: Boolean@deprecated(reason: "Use `check`.")
check: String
}

@skip#

The@skipdirective may be used for fields, fragment spreads, and inline fragments, and allows for conditional exclusion during execution of a query as described by the if argument. Please note this directive is used while executing query in GraphQL editor and not in the schema editor like other directives.

directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

In the below example, check field will only be queried if the variable$someTesthas the value false. If the value is true, the field will be skipped from the query execution.

query($someTest: Boolean!){
find(type: checkSkip, arcql: "*") {
edges {
node {
... on checkSkip {
check @skip(if:$someTest)
}
}
cursor
}
}
}

@include#

Similar to the @skip directive, The@includedirective may be used for fields, fragment spreads, and inline fragments. It allows conditional inclusion during the execution of a query as described by the if argument.

directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

In the below example, check field will only be queried if the variable$someTesthas the value true. If the value is false, the field will not be included in the query execution.

query($someTest: Boolean!){
find(type: checkSkip, arcql: "*") {
edges {
node {
... on checkSkip {
check @include(if:$someTest)
}
}
cursor
}
}
}

@specifiedBy#

Hypi does not support this directive at the moment.