Skip to main content

Knowledge Base Layer

The knowledge-base layer (kb) is where the magic happens. The idea behind the kb layer is to model your data semantically, i.e. as if you would be explaining to a person what your database is really about.

The idea sounds familiar? You have probably heard about Entity-Relationship modelling. Well, that's pretty much what we are doing here. Instead of talking about views/tables/columns, which is just the physical representation of information, we will model it closer to the business domain.

For this modelling, we have to introduce the vocabulary:

  • Classes (in ER-modelling they are known as Entity Types)
  • Entities
  • Relationships
  • Attributes

Let's see in detail what each of these things actually mean.

Classes and Entities​

If you come from a software background, you may be familiar with the idea of a class as defined in object-oriented programming. In some sense, we are making your data more object-oriented. So, a class can be defined as a category of things. The best way to understand it is to go over some examples.

A class could be something like:

  • Customer
  • Country
  • Order
  • Movie

Now, each of these classes may have instantiations of it. In programming, we call these "objects". In VKL, we call them entities. So following our example, we may have entities like:

  • entity Till_Haug of class Customer
  • entity Brazil of class Country
  • entity Batman of class Movie

But what about Order? For classes like Order, Transaction and Event, it makes sense usually to model it as a class without entities. Prefer to use classes with entities when there is a way to refer to an individual of this class in a question.

Here is an example of a class in VKL:

import: [
    db.postgres.movie_db.public.ORDERS
]

kb {
    class Customer {
        name.en: "Customer"     
        synonym.en: "Client"
        extends: onto.Customer
        
        sql: "${ORDERS.customer_id}"
        name_sql.en:
          "${ORDERS.customer_firstname} || ' ' || ${ORDERS.customer_lastname}"

        ...
    }
}

To learn more about how classes and entities are defined in VKL here:

Relationships​

A relationship in VKL describes how classes relate to each other.

Example:

  • Till_Haug works at Veezoo_AG
  • JP_Monteiro is from the segment Consumer
  • Rio_de_Janeiro is located in Brazil

In other words, we have the following relationships:

  • works_at is a relationship that goes from Employee to Company
  • from_segment is a relationship that goes from Customer to the class Segment
  • located_in is a relationship that goes from City to the class Country

Here is an example of a relationship in VKL:

import: [
    db.postgres.movie_db.public.ORDER
]

kb {

    class Order {
        name.en: "Order"
        sql: "${ORDER.id}"

        ...

        relationship from_Customer {
            to: kb.Customer

            sql: "${ORDER.customer_id}"
        }

        ...
    }
}

Learn about how relationships are defined in VKL here:

Attributes​

Attributes are properties of a class and they can be of the following types: number / integer, date, boolean, string and class as well.

Numeric attributes​

Examples:

kb {

    class Country {

        ...

        /** e.g. Brazil has a population of 209,500,000 inhabitants. */
        integer Population {
            name.en: "Population"
            
            sql: "${COUNTRY.population}"
        }

        /** e.g. USA has a GDP of 21.43 trillion USD. */
        number Gross_Domestic_Product {
            name.en: "Gross Domestic Product"
            synonym.en: "GDP"
            unit: onto.Currency.USD
            
            sql: "${COUNTRY.gdp_in_usd}"
        }

        ...
    }
}

Learn more about numeric attributes here.

Date attributes​

Example:

kb {

    class Customer {

        ...

        /** e.g. JP was born on 30th of March 1993. */
        date Birthdate {
            name.en: "Birthdate"
            extends: onto.Birthdate
            datetime_format: DayFormat
            
            sql: "${CUSTOMER.birthdate}"
        }

        ...
    }
}

Learn more about date attributes here.

Boolean attributes​

Example:

kb {

    class Order {

        ...

        boolean Returned {
            name.en: "Returned"

            sql: "${ORDERS.returned} = 'yes'"
        }
    }
}

Learn more about boolean attributes here.

Class attributes​

Example:

kb {

    class Customer {

        ...

        /** e.g. JP is from the segment Young&Professionals. */
        class Segment {
            name.en: "Segment"
            
            sql: "${CUSTOMER.segment}"
        }

        ...
    }
}

This may strike at first as weird. Why not just model it as a string?

By modelling as a class with entities, you get to refer to the individual values (entities) in a question, since Veezoo will index them to understand you. This way you can ask 'How many Corporate customers do we have?' and Veezoo will recognize the entity 'Corporate' of class 'Segment', while helping you with AutoComplete.

The way you have to think about it is: is it actual text (e.g. that you would want to search inside)? If not, it's probably a class.

A free-text comment field? It's a string in Veezoo.

A customer? It's a class.

The first name of a customer? If this is relevant as a standalone concept for your business users, then sure, it's a string. Otherwise, just use it as part of the name_sql, e.g. "${CUSTOMER.first_name} || ' ' || ${CUSTOMER.last_name}".

Learn more about class attributes here.

String attributes​

Example:

kb {

    class Company {

        ...

        /** e.g. Veezoo has the URL "https://www.veezoo.com". */
        string Website_URL {
            name.en: "Website"
            extends: onto.URL
            
            sql: "${COMPANY.website_url}"
        }

        ...
    }
}

Learn more about string attributes here.