diff --git a/docs/.pages b/docs/.pages index 41abd5958..85cf02585 100644 --- a/docs/.pages +++ b/docs/.pages @@ -1,5 +1,8 @@ --- nav: + - Home: + - index.md + - introduction - Build: build - Explore: explore-and-author - Consume: consume @@ -9,4 +12,3 @@ nav: - Develop: develop - Release Notes: release-notes - Tutorials: tutorials - diff --git a/docs/develop/index.md b/docs/develop/index.md index 5f06d9805..b83463683 100644 --- a/docs/develop/index.md +++ b/docs/develop/index.md @@ -1,5 +1,7 @@ --- icon: material/star-outline +hide: + - toc --- # Develop diff --git a/docs/graph-insights-suppliers-products-countries.png b/docs/graph-insights-suppliers-products-countries.png new file mode 100644 index 000000000..1a6acc5b6 Binary files /dev/null and b/docs/graph-insights-suppliers-products-countries.png differ diff --git a/docs/index.md b/docs/index.md index 7bf4f865b..965e813da 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,31 +1,18 @@ --- +title: "Welcome to the eccenca Corporate Memory documentation" +icon: material/home comments: false -hide: - - toc - - navigation --- # Welcome to the eccenca Corporate Memory documentation
-- :material-calendar: [Release Notes](release-notes/2024/corporate-memory-24-3/index.md) +- :material-home: [Home](#what-is-eccenca-corporate-memory) --- - Documentation of changes and enhancements for each version. - -- :material-list-status: [Tutorials](tutorials/index.md) - - --- - - Learn by example and step-by-step guidelines to achieve a concrete goal fast. - -- :material-arrow-right-thick: [Getting Started](getting-started/index.md) - - --- - - This page describes how to work with Corporate Memory and shortly outlines all functionalities of the user interface. + New to eccenca Corporate Memory? Start here: what the product is for, how it is structured, and how to get access. - :material-star: [Build](build/index.md) @@ -69,4 +56,156 @@ hide: Extend Corporate Memory with custom plugins and packages, and access it programmatically through the Python, Java and REST APIs. +- :material-calendar: [Release Notes](release-notes/2026/corporate-memory-26-2/index.md) + + --- + + Documentation of changes and enhancements for each version. + +- :material-list-status: [Tutorials](tutorials/index.md) + + --- + + Learn by example and step-by-step guidelines to achieve a concrete goal fast. +
+ +## What is eccenca Corporate Memory? + +Corporate Memory connects data that lives in separate systems into one meaningful whole, a knowledge graph. +It keeps that whole usable as the systems and the business around it change. + +Prefer to watch? +The video [eccenca Corporate Memory in 3 minutes](https://www.youtube.com/watch?v=Lb0zpH9oLMM){target=_blank} shows what Corporate Memory is for, without a product demo. + +[![Video eccenca Corporate Memory in 3 minutes on YouTube: a knowledge graph answering which products are affected if Kessler GmbH fails](video-corporate-memory-in-3-minutes.jpg){ class="bordered off-glb" width="60%" }](https://www.youtube.com/watch?v=Lb0zpH9oLMM){target=_blank} + +Reading time: 4 minutes. +No prior knowledge is required. +The following sections explain what the product is for, not how to use it. + +### A familiar problem + +A supplier has just gone out of business. +Someone in purchasing needs to know which products are affected. + +The answer exists. +But the product is called `P-10045` in the ERP system, `PRD_10045_A` in the PLM system and `45100-XX` in the supplier portal. +Each system is right on its own terms, and none of them knows about the others. +So the answer is put together by hand, takes days, and is out of date by the time anyone acts on it. + +Most organizations do not have a data shortage. +They have a connection problem. + +### What eccenca Corporate Memory does + +![Left: three systems with three names for the same product. Right: the same product, connected by named relationships.](three-systems-one-product.png){ class="bordered" } + +Corporate Memory gives the context of the data a place to live. + +It reads data from existing systems and expresses it as a knowledge graph: things, and the named relationships between them. +This product is made at this plant. +This plant is supplied by this company. +Each statement is written down explicitly, in a form both people and software can follow. + +The three identifiers do not disappear. +They become properties of one product, so any fact can be traced back to the system it came from, and written back to it where that makes sense. + +The question from purchasing now has a place to be asked, and an answer that is the same for everyone who asks it. + +![Suppliers, the products they supply and the countries they are in, shown in Graph Insights. Every connection carries a name.](graph-insights-suppliers-products-countries.png){ class="bordered" width="60%" } + +Around the graph, the platform provides what is needed to keep it alive: building it from real sources, exploring and correcting it, checking that it still meets expectations, and serving it to the people and applications that need answers. + +- [What is a knowledge graph?](introduction/what-is-a-knowledge-graph/index.md) explains the idea in more depth. +- [eccenca Corporate Memory at a glance](introduction/corporate-memory-at-a-glance/index.md) shows how the parts of the product fit together. + +### Terms used in this documentation + +These terms are not needed for this introduction. +They become useful once reading continues into the other sections. + +| Term | In one line | +| --- | --- | +| Mapping | How source columns become things and relationships in the graph. | +| Linking | Deciding when two records from different systems mean the same thing. | +| Shapes (SHACL) | Writing down what must be true about the data, and checking it. | +| Vocabulary | The agreed names for the kinds of things and relationships in use. | +| Workflow | Running all of it again whenever the sources change. | +| Marketplace | Ready-made packages to install and adapt. | +| cmemc | Doing the same from the command line, for automation and CI/CD. | + +### What it is and what it is not + +| Corporate Memory is … | … and it is not | +| --- | --- | +| a layer that connects with existing systems | a replacement for them; the ERP system stays the ERP system | +| built to represent meaning and relationships | a data warehouse or a BI tool for aggregating numbers | +| configured for business users by people who know the data and the domain | a finished application for end users | +| support for modeling decisions | a way to avoid them | + +It does not wire the systems to each other either. +Corporate Memory connects with them, brings their data together in one graph, and leaves them running as they are. + +The last row matters most. +Deciding what the data means is modeling work. +Corporate Memory supports that work, it does not do it. + +### Is it the right tool? + +Corporate Memory is likely to add value when most of these questions are answered with yes: + +- Do the questions cross system boundaries? +- Is the same real-world thing represented differently in different places? +- Do relationships matter as much as the values themselves? +- Is the structure of the data expected to keep changing? + +It is probably not the right tool for a single well-structured source with a stable schema, or for a question that is essentially "sum this column by month". +It is also not the right tool when nobody in the organization is available to decide what the data means. +That last one is the most common reason such projects stall, and no software solves it. + +### Who works with it + +
+ +- __Linked Data Experts and data engineers__ + + --- + + Do most of the building: connect sources, model, and keep the graph current. + + [:octicons-arrow-right-24: Build a knowledge graph](build/index.md) + +- __Business users__ + + --- + + Work with what has been configured for them, usually without seeing the model behind it. + + [:octicons-arrow-right-24: Explore and manage knowledge](explore-and-author/index.md) + +- __Developers__ + + --- + + Integrate Corporate Memory with other applications and extend it. + + [:octicons-arrow-right-24: Extend Corporate Memory](develop/index.md) + +- __Administrators__ + + --- + + Install, operate and upgrade it. + + [:octicons-arrow-right-24: Deploy and operate](deploy-and-configure/index.md) + +
+ +Choosing one of these roles is not required at this point. + +### Next + +- [What is a knowledge graph?](introduction/what-is-a-knowledge-graph/index.md): the concept, 5 minutes, on the main path +- [Semantic Web basics](introduction/semantic-web-basics/index.md): optional, the terminology, about 35 minutes +- [eccenca Corporate Memory at a glance](introduction/corporate-memory-at-a-glance/index.md): the parts of the product and how they relate diff --git a/docs/introduction/.pages b/docs/introduction/.pages new file mode 100644 index 000000000..c55bbbe0d --- /dev/null +++ b/docs/introduction/.pages @@ -0,0 +1,7 @@ +--- +nav: + - "What is a knowledge graph?": what-is-a-knowledge-graph + - Semantic Web basics: semantic-web-basics + - At a glance: corporate-memory-at-a-glance + - Get access: get-access + - See it in the product: see-it-in-the-product diff --git a/docs/introduction/corporate-memory-at-a-glance/corporate-memory-overview.png b/docs/introduction/corporate-memory-at-a-glance/corporate-memory-overview.png new file mode 100644 index 000000000..2cc11d276 Binary files /dev/null and b/docs/introduction/corporate-memory-at-a-glance/corporate-memory-overview.png differ diff --git a/docs/introduction/corporate-memory-at-a-glance/index.md b/docs/introduction/corporate-memory-at-a-glance/index.md new file mode 100644 index 000000000..6014177d7 --- /dev/null +++ b/docs/introduction/corporate-memory-at-a-glance/index.md @@ -0,0 +1,89 @@ +--- +title: "Introduction: eccenca Corporate Memory at a glance" +--- + +# eccenca Corporate Memory at a glance + +[What is a knowledge graph?](../what-is-a-knowledge-graph/index.md) explains the knowledge graph in the middle of the following picture. +The five areas around it are where the work with that graph happens. +Each area is a part of eccenca Corporate Memory, and each has its own section in this documentation. +The following descriptions say what each one is for, in two or three sentences, and nothing about how to use it. + +![Overview of Corporate Memory: the knowledge graph in the center, connected to Build, Explore and Consume, with Govern and Distribute across all three](corporate-memory-overview.png){ width="80%" } + +## Build + +Build is where data becomes a knowledge graph. +A source is connected: a file, a database, an API. +Its columns are then defined as things and relationships, and the Mapping Creator proposes most of that. +Workflows put the steps in order, so the graph can be rebuilt whenever the sources change. + +Mostly used by Linked Data Experts and data engineers. + +[:octicons-arrow-right-24: Go to Build](../../build/index.md) + +## Explore + +Explore is where people work with the graph. +Searching finds a thing, its connections become visible, and what is wrong is corrected in place, without a query language. +Views can be tailored to a task, so a colleague sees their own fields rather than the model behind them. + +Used by business users and Linked Data Experts. + +[:octicons-arrow-right-24: Go to Explore](../../explore-and-author/index.md) + +## Consume + +Consume is where other systems take over. +Dashboards, applications, automated processes and AI agents read the same graph through standard interfaces such as SPARQL, SQL and REST. +Everyone then works from the same answer instead of a copy of their own. + +Used by developers, analysts and Linked Data Experts. + +[:octicons-arrow-right-24: Go to Consume](../../consume/index.md) + +## Govern + +Govern is what keeps the whole thing dependable. +Access rules decide who sees and changes what, and metrics and logs show whether the system is healthy. +Everything that can be done by hand can also be done from the command line or through an API. +That is what makes automation and continuous delivery possible. + +Used by administrators and operations teams. + +[:octicons-arrow-right-24: Go to Automate](../../automate/index.md) · [:octicons-arrow-right-24: Go to Deploy and Configure](../../deploy-and-configure/index.md) + +## Distribute + +Distribute is how work gets reused. +The Marketplace holds ready-made content that can be added to an instance: vocabularies, taxonomies, data graphs, Build projects and query catalogs. +Complete demo and solution setups are included. +Everything arrives as a versioned package, and Corporate Memory puts its contents where they belong. +Solutions built in house can be packaged and shared the same way. + +Used by Linked Data Experts and developers. + +[:octicons-arrow-right-24: Go to Distribution](../../distribution/index.md) + +## What else it can do + +The five areas above are where most work happens. +The following capabilities exist alongside them, and are named here so that they are known to exist rather than explained. + +| Capability | In one line | Where | +| --- | --- | --- | +| Query and SPARQL | The query language for graphs, and the precise way to ask the data a question nobody planned for. | [Queries](../../explore-and-author/query-module/index.md) | +| Reasoning | Derives the facts that follow from the data and the rules, without anyone stating them. | [Reason](../../build/reference/customtask/cmem_plugin_reason-plugin_reason-ReasonPlugin.md) | +| Shapes (SHACL) | Record what must be true about the data, and check whether it is. | [Building a customized user interface](../../explore-and-author/graph-exploration/building-a-customized-user-interface/index.md) | +| Linking rules | Decide when two records from different systems mean the same real-world thing. | [Link Rules](../../explore-and-author/link-rules/index.md) | +| Link learning | Proposes those rules from examples, instead of requiring them to be written by hand. | [Active Learning](../../build/active-learning/index.md) | +| Python plugins | Add functions that the standard product does not provide. | [Python Plugins](../../develop/python-plugins/index.md) | +| Deployment | The technical operating layer, so Corporate Memory runs in different environments. | [Deploy and Configure](../../deploy-and-configure/index.md) | + +## Next + +- [Get access](../get-access/index.md): a sandbox or an existing instance +- Basic, the hands-on path to a first knowledge graph in about four hours, is in preparation. + Until then, the [Tutorials](../../tutorials/index.md) cover the first steps. + + diff --git a/docs/introduction/get-access/eccenca-my-email-verification.png b/docs/introduction/get-access/eccenca-my-email-verification.png new file mode 100644 index 000000000..a506056fb Binary files /dev/null and b/docs/introduction/get-access/eccenca-my-email-verification.png differ diff --git a/docs/introduction/get-access/eccenca-my-register-form.png b/docs/introduction/get-access/eccenca-my-register-form.png new file mode 100644 index 000000000..d3e4dcf27 Binary files /dev/null and b/docs/introduction/get-access/eccenca-my-register-form.png differ diff --git a/docs/introduction/get-access/eccenca-my-terms-and-conditions.png b/docs/introduction/get-access/eccenca-my-terms-and-conditions.png new file mode 100644 index 000000000..f0f53040d Binary files /dev/null and b/docs/introduction/get-access/eccenca-my-terms-and-conditions.png differ diff --git a/docs/introduction/get-access/eccenca-my-your-sandboxes.png b/docs/introduction/get-access/eccenca-my-your-sandboxes.png new file mode 100644 index 000000000..85885eb2f Binary files /dev/null and b/docs/introduction/get-access/eccenca-my-your-sandboxes.png differ diff --git a/docs/introduction/get-access/index.md b/docs/introduction/get-access/index.md new file mode 100644 index 000000000..ad5cea796 --- /dev/null +++ b/docs/introduction/get-access/index.md @@ -0,0 +1,80 @@ +--- +title: "Introduction: Get access to the sandbox" +--- + +# Get access to the sandbox + +The eccenca Corporate Memory sandbox is a free, personal Corporate Memory instance for trying out the product. +It is provided at [eccenca.my](https://eccenca.my/) as the Community Edition sandbox. + +The following steps register an account at eccenca.my and sign in to the sandbox. +The result is a running sandbox that serves as the starting point for the tutorials in this documentation. + +For the content that a new sandbox includes, and for its limitations, see [Welcome to your eccenca Corporate Memory Sandbox](../../getting-started/with-your-sandbox/index.md). + +!!! info "Existing instance" + + With access to an existing Corporate Memory instance, no registration is needed. + Open the URL of the instance and sign in with the credentials provided by its administrator, as described in [Login and Logout](../../getting-started/index.md#login-and-logout). + +## Prerequisites + +The following items are required: + +- An email address that receives the messages from eccenca.my +- A supported web browser, as listed under [Minimal requirements](../../getting-started/index.md#minimal-requirements) + +## Register an account + +1. Open [eccenca.my](https://eccenca.my/) in a web browser. +2. Click **GET STARTED**. + The eccenca.my sign-in form opens. +3. Click **Register**. + The **Register** form opens. +4. Enter the following values: + + - **First name:** the first name of the account holder + - **Last name:** the last name of the account holder + - **Email:** the email address that is used to sign in + - **Password:** a password for the account + - **Confirm password:** the same password again + + ![Register form at eccenca.my with the fields First name, Last name, Email, Password and Confirm password](eccenca-my-register-form.png){ class="bordered" width="50%" } + +5. Click **REGISTER**. + The **Terms and Conditions** dialog opens. + It covers the eccenca.my terms of service, the data privacy policy and the Ontotext GraphDB Free license agreement. + + ![Terms and Conditions dialog at eccenca.my](eccenca-my-terms-and-conditions.png){ class="bordered" width="50%" } + +6. Click **ACCEPT**. + The **Email verification** form opens, and eccenca.my sends an email with instructions to verify the email address. + + ![Email verification form at eccenca.my](eccenca-my-email-verification.png){ class="bordered" width="50%" } + +7. Follow the instructions in the email to verify the email address. + The account is activated, and the **Your Sandboxes** overview opens. + +## Request a sandbox + +1. In the **Your Sandboxes** overview, click **Request Sandbox**. + + ![Your Sandboxes overview at eccenca.my with the Request Sandbox button](eccenca-my-your-sandboxes.png){ class="bordered" width="50%" } + +2. Enter a name of choice for the instance in the form. + +The provisioning of the sandbox takes up to 24 hours. +When the sandbox is ready, eccenca.my sends an email with the link to the sandbox and its credentials. + +## Open the sandbox + +1. Open the link from the email that announces the sandbox. +2. Sign in with the credentials from the same email. + +## Next + +- [See it in the product](../see-it-in-the-product/index.md): five features, with the documentation for each +- Basic, the guided path from a source file to a knowledge graph in about four hours, is in preparation. + Until then, the [Tutorials](../../tutorials/index.md) cover the first steps. + + diff --git a/docs/introduction/see-it-in-the-product/bke-canvas-product.png b/docs/introduction/see-it-in-the-product/bke-canvas-product.png new file mode 100644 index 000000000..49e2cd1d7 Binary files /dev/null and b/docs/introduction/see-it-in-the-product/bke-canvas-product.png differ diff --git a/docs/introduction/see-it-in-the-product/companion-chat-answer.png b/docs/introduction/see-it-in-the-product/companion-chat-answer.png new file mode 100644 index 000000000..5cbf699e7 Binary files /dev/null and b/docs/introduction/see-it-in-the-product/companion-chat-answer.png differ diff --git a/docs/introduction/see-it-in-the-product/graph-insights-overview.png b/docs/introduction/see-it-in-the-product/graph-insights-overview.png new file mode 100644 index 000000000..1a6acc5b6 Binary files /dev/null and b/docs/introduction/see-it-in-the-product/graph-insights-overview.png differ diff --git a/docs/introduction/see-it-in-the-product/index.md b/docs/introduction/see-it-in-the-product/index.md new file mode 100644 index 000000000..4bb6a6552 --- /dev/null +++ b/docs/introduction/see-it-in-the-product/index.md @@ -0,0 +1,97 @@ +--- +title: "Introduction: See it in the product" +--- + +# See it in the product + +The five features below are the ones a newcomer to eccenca Corporate Memory meets first. +Each is shown once, with a link to the documentation that covers it. + +Nothing here has to be understood or operated yet. +Looking is enough. + + + + + +## Graph Insights + + + +Graph Insights shows a knowledge graph as a readable picture: similar things are grouped, and the connections between the groups are summarized. +Each step offers only the relationships the data actually uses, so no path leads to an empty view. +Filters narrow what is shown, and no query is needed. + +![Graph Insights showing suppliers, the products they supply, product categories and countries](graph-insights-overview.png){ class="bordered" width="60%" } + +[:octicons-arrow-right-24: Graph Insights](../../explore-and-author/graph-exploration/graph-insights/index.md) + +## Business Knowledge Editor + + + +The Business Knowledge Editor is where an individual thing in a knowledge graph is read and changed. +It appears as a diagram with its relationships, labeled with the names the business uses. +Both can be added to or edited. +Any changes become part of the graph, so everything built on it sees them. + +![Business Knowledge Editor showing a product with its price, categories, supplier and responsible department](bke-canvas-product.png){ class="bordered" width="60%" } + +[:octicons-arrow-right-24: Business Knowledge Editor](../../explore-and-author/bke-module/index.md) + +## Shape views + +Shape views present graph data in whatever form a task needs: a form with business field labels, a map, a diagram. +The presentation follows the model rather than code, so a change to the model changes every view built on it. + +![Shape view of the supplier White-Nash (Pakistan) in Explore: a map preview of its location above fields with business labels such as locality (city) and country code](shape-view-supplier-form-with-map.png){ class="bordered" width="60%" } + +[:octicons-arrow-right-24: Building a customized user interface](../../explore-and-author/graph-exploration/building-a-customized-user-interface/index.md) + +## Mapping Creator + +The Mapping Creator connects the columns of a source to the things and relationships of the knowledge graph. +The mapping is drawn as lines between source and target, by hand or proposed by artificial intelligence (AI). +Each suggestion is accepted or rejected by a person, individually or in bulk. +The tedious half of the work is proposed, while the decision about what the data means stays with a person. + +![Mapping Creator connecting the columns of a supplier source to the properties of the Supplier class](mapping-creator-supplier-mapping.png){ class="bordered" width="60%" } + +[:octicons-arrow-right-24: Mapping Creator](../../build/mapping-creator/index.md) + +## Companion + +Companion is an AI agent built into Corporate Memory. +A question about the data, asked in plain language, is answered from the knowledge graph. +That opens the graph to people who never write a query. +Intentions for a data pipeline, described in plain language, are translated into Build workflows, transformations and other tasks. + +![Companion answering a question about hardware items and their suppliers](companion-chat-answer.png){ class="bordered" width="40%" } + +[:octicons-arrow-right-24: Companion AI Chat](../../explore-and-author/companion/index.md) + +## Next + +- Basic, the hands-on path to a first knowledge graph in about four hours, is in preparation. + Until then, the [Tutorials](../../tutorials/index.md) cover the first steps. + + + +## Browse all documentation + +The complete documentation is organized by module: +[Build](../../build/index.md) · +[Explore](../../explore-and-author/index.md) · +[Consume](../../consume/index.md) · +[Distribution](../../distribution/index.md) · +[Deploy and Configure](../../deploy-and-configure/index.md) · +[Automate](../../automate/index.md) · +[Develop](../../develop/index.md) · +[Release Notes](../../release-notes/2026/corporate-memory-26-2/index.md) · +[Tutorials](../../tutorials/index.md) diff --git a/docs/introduction/see-it-in-the-product/mapping-creator-supplier-mapping.png b/docs/introduction/see-it-in-the-product/mapping-creator-supplier-mapping.png new file mode 100644 index 000000000..531cc7d91 Binary files /dev/null and b/docs/introduction/see-it-in-the-product/mapping-creator-supplier-mapping.png differ diff --git a/docs/introduction/see-it-in-the-product/shape-view-supplier-form-with-map.png b/docs/introduction/see-it-in-the-product/shape-view-supplier-form-with-map.png new file mode 100644 index 000000000..961cccd9f Binary files /dev/null and b/docs/introduction/see-it-in-the-product/shape-view-supplier-form-with-map.png differ diff --git a/docs/introduction/semantic-web-basics/explore-copy-resource-identifier.png b/docs/introduction/semantic-web-basics/explore-copy-resource-identifier.png new file mode 100644 index 000000000..d13db86ea Binary files /dev/null and b/docs/introduction/semantic-web-basics/explore-copy-resource-identifier.png differ diff --git a/docs/introduction/semantic-web-basics/explore-resource-properties-tab.png b/docs/introduction/semantic-web-basics/explore-resource-properties-tab.png new file mode 100644 index 000000000..afe1db36a Binary files /dev/null and b/docs/introduction/semantic-web-basics/explore-resource-properties-tab.png differ diff --git a/docs/introduction/semantic-web-basics/index.md b/docs/introduction/semantic-web-basics/index.md new file mode 100644 index 000000000..d88f88902 --- /dev/null +++ b/docs/introduction/semantic-web-basics/index.md @@ -0,0 +1,169 @@ +--- +title: "Introduction: Semantic Web basics" +tags: + - KnowledgeGraph + - Vocabulary +--- + +# Semantic Web basics + +This is a compact overview of the terms that the rest of this documentation assumes. +Those terms are triple, Internationalized Resource Identifier (IRI), literal, prefix, class, property, vocabulary and graph. +Each term is shown as it appears in eccenca Corporate Memory. + +The overview is optional and takes about 35 minutes. +It is a bridge, not a course. +It covers enough to read the documentation and to work with the product, and points to a full course for everything beyond that. + +Skip ahead when triple, IRI and vocabulary are familiar terms. +Nothing here is specific to Corporate Memory that does not also appear later. +Read on when Resource Description Framework (RDF) and ontology are words heard but never used. +Either way, the introduction continues with [eccenca Corporate Memory at a glance](../corporate-memory-at-a-glance/index.md). + +## Why the meaning has to be written down + +Software reads text without understanding it. + +"The fisherman went to the bank" is clear to a reader and ambiguous to a machine, which cannot tell a riverbank from a financial institution. +A person resolves this from context. +Software has no context unless the context is recorded. + +The same applies to structure. +A column headed `loc` is meaningful to the team that created it and opaque to everyone else, including every program that reads the table later. + +The terms are the agreed way of recording what something is and how it relates to other things. +Their purpose is that the meaning travels with the data instead of living in someone's head. + +[What is a knowledge graph?](../what-is-a-knowledge-graph/index.md) explains why a graph is the shape that makes this possible. + +## The terms + +### Triple + +A triple is the smallest complete statement: subject, predicate, object. +`Product 10045` — is made at — `Plant Leipzig` is one triple. +A knowledge graph is a large collection of triples. + +![The triple Product 10045, is made at, Plant Leipzig, with Product 10045 as the subject, is made at as the predicate and Plant Leipzig as the object](triple-subject-predicate-object.svg){ class="bordered" } + +In the product: open a resource in Explore and select the **Properties** tab. +The resource is the subject, and each row is one predicate with its object. + +![Properties tab of the resource C247-3833661 - Encoder Transformer, with one row per predicate and its object](explore-resource-properties-tab.png){ class="bordered" width="70%" } + +### IRI + +An IRI identifies a thing, globally and uniquely, and is written like a web address: `https://example.org/product/10045`. +IRI is the internationalized form of Uniform Resource Identifier (URI). + +A plain number does not work for this purpose. +The number `10045` means something different in each source system, while an IRI cannot collide with another system's identifier. + +In the product: **Copy resource identifier** in the :eccenca-item-moremenu: menu of a resource copies its IRI. + +![Menu of a resource in Explore with the entry Copy resource identifier](explore-copy-resource-identifier.png){ class="bordered" width="40%" } + +### Literal, datatype and language tag + +A literal is a value rather than a thing: a number, a date, a piece of text. +IRIs name the things, literals hold what is known about them. + +By default a literal is text. +`"12.3833"` looks like a number but sorts like text, which puts `"02"` before `"100"` before `"11"`. +A datatype fixes this: `"12.3833"^^xsd:decimal` is a number and sorts like one. + +A text literal can also carry a language tag, so one thing can have a label in several languages at once: `"Leipzig"@de` and `"Lipsia"@it`. + +In the product: the **Properties** tab distinguishes the two. +A value shown as plain text, such as `58` for **height (mm)**, is a literal. +A value shown as a chip, such as **White-Nash (Pakistan)** for **supplier**, is a link to another thing. + +### Prefix + +A prefix is a shorthand for the long part of an IRI. +Declaring `ex:` for `https://example.org/` shortens the identifier above to `ex:product/10045`. + +In the product: prefixes are managed per project and are chosen while a mapping is built, which makes them worth choosing deliberately. + +### Class and property + +A class is a kind of thing, such as a product, a plant or a supplier. +A property is a kind of statement that can be made about a thing, such as is made at or has article number. + +Classes and properties are themselves things with IRIs. +This is what makes a graph self-describing: the description of the data lives in the same graph as the data. + +In the product: the class tree in Explore lists the classes, and the rows of a resource view are its properties. + +### Vocabulary and ontology + +A vocabulary is the agreed set of classes and properties for a domain. +It is the shared answer to what things are called and which statements may be made about them. +Vocabularies exist for many common domains, and reusing one is usually better than inventing another. + +In practice the two words are used interchangeably. +Where a distinction is made, ontology implies formal rules about what follows from what. + +In the product: the Vocabulary Catalog holds the vocabularies, and a target vocabulary is selected when a mapping is started. + +### Graph + +A graph is a named container for triples. +Data does not land in one undifferentiated heap. +It goes into a named graph, so that it can be replaced, versioned or kept apart from other data. + +In the product: the target graph is selected when a workflow is set up. + +## What this looks like written down + +A graph has to be written to a file in order to be exchanged, and the common format for that is Turtle. + +```turtle +@prefix ex: . +@prefix rdfs: . +@prefix xsd: . + +ex:product10045 + a ex:Product ; + rdfs:label "Product 10045"@en ; + ex:articleNumber "10045" ; + ex:weight "4.2"^^xsd:decimal ; + ex:madeAt ex:plantLeipzig . +``` + +Every term above appears in those few lines. +There are three prefixes and their IRIs, a class after `a`, four properties, and literals with a language tag and a datatype. +The keyword `a` states the class of the subject, and is the Turtle shorthand for the property `rdf:type`. +The semicolons group statements that share a subject. + +Writing Turtle by hand is not required in order to work with Corporate Memory. +Recognizing it is useful, because an exported graph looks like this. + +## What is left out + +Three subjects are named in the documentation and deliberately left out here: + +- SPARQL is the query language for graphs. + Much of Explore works without writing any, and the [Queries](../../explore-and-author/query-module/index.md) documentation covers it where it is needed. +- Shapes Constraint Language (SHACL) records what must be true about the data. + It is used both for validation and for shaping the forms that people see. +- Modeling techniques such as blank nodes and relations between more than two things belong next to the task that needs them, in the [Build](../../build/index.md) documentation. + +## Going deeper + +The recommended course is [Knowledge Graphs – Foundations and Applications](https://open.hpi.de/courses/knowledgegraphs2023) by Prof. Dr. Harald Sack of FIZ Karlsruhe and Karlsruhe Institute of Technology, hosted on openHPI. +The course consists of six weeks of material and a final exam. +It is held in English, is free of charge, and is available in self-study mode at any time. + +Self-study mode leads to a Confirmation of Participation. +Graded certificates require a live course run, so the course page is the place to check for the next one. + +The group behind the course publishes further material openly at Information Service Engineering, FIZ Karlsruhe. + + +This documentation links to these resources rather than reproducing them. +They are maintained by the people who teach them. + +## Next + +- [eccenca Corporate Memory at a glance](../corporate-memory-at-a-glance/index.md): the parts of the product and how they relate diff --git a/docs/introduction/semantic-web-basics/triple-subject-predicate-object.svg b/docs/introduction/semantic-web-basics/triple-subject-predicate-object.svg new file mode 100644 index 000000000..8f6597b33 --- /dev/null +++ b/docs/introduction/semantic-web-basics/triple-subject-predicate-object.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + SUBJECT + PREDICATE + OBJECT + + + + + + + + + is made at + + + + + + + Product 10045 + Plant Leipzig + + + One triple: one complete statement about one thing + diff --git a/docs/introduction/what-is-a-knowledge-graph/following-a-question-through-the-graph.svg b/docs/introduction/what-is-a-knowledge-graph/following-a-question-through-the-graph.svg new file mode 100644 index 000000000..8edca79ee --- /dev/null +++ b/docs/introduction/what-is-a-knowledge-graph/following-a-question-through-the-graph.svg @@ -0,0 +1,81 @@ + + + + + + + + + + + + + + Supplier + Plants + Products + + + + + + + + + + + + + + + + + + + is supplied by + is made at + + + is supplied by + is made at + + + + + + + + + + + + + + + + + + + + + Kessler GmbH + Plant Leipzig + Plant Dresden + Product 10045 + Product 10046 + Product 10047 + + + Berger AG + Plant Hamburg + Product 10048 + + + + + + affected by the supplier failure + + not affected + + diff --git a/docs/introduction/what-is-a-knowledge-graph/index.md b/docs/introduction/what-is-a-knowledge-graph/index.md new file mode 100644 index 000000000..c880fed77 --- /dev/null +++ b/docs/introduction/what-is-a-knowledge-graph/index.md @@ -0,0 +1,92 @@ +--- +title: "Introduction: What is a knowledge graph?" +tags: + - KnowledgeGraph +--- + +# What is a knowledge graph? + +A knowledge graph records things and the named relationships between them, in a form that both people and software can follow. + +The documentation uses the term throughout, because it is what eccenca Corporate Memory builds and works with. +The terms that come with it, such as triple, Internationalized Resource Identifier (IRI) and vocabulary, are covered in [Semantic Web basics](../semantic-web-basics/index.md), which is optional. + +## Things and relationships + +Most business data lives in tables. +A table is a good answer to a question that was known in advance. +Its columns are fixed, and every row answers the same question in the same shape. + +The questions that cause trouble are the ones nobody planned for. +Which products are affected if a supplier fails? +The answer usually exists, spread over several systems, each with its own name for the same product. +Producing it means a join that somebody writes and somebody else maintains. + +A knowledge graph turns that around. +Instead of rows in fixed columns, it records the things themselves and how they are connected: + +- Product 10045: is made at Plant Leipzig +- Plant Leipzig: is supplied by Kessler GmbH + +![Product 10045 is made at Plant Leipzig, and Plant Leipzig is supplied by Kessler GmbH, shown as three things connected by two named relationships](things-and-named-relationships.svg){ class="bordered" } + +Each connection carries a name. +"Is made at" is not a column heading that a reader has to interpret, and not a foreign key that only the application understands. +It is a statement, written down, that software can follow as reliably as a person can read it. + +## What that changes + +Three things follow, and they are the reason the term appears in this documentation at all. + +New questions need no new structure. +Anything connected can be followed, in any direction, without that path having been planned. +The question about the failed supplier is answered by walking from the supplier to the plants to the products. +Nobody has to have anticipated it. + +![The path from the failed supplier Kessler GmbH over the plants it supplies to the products made there, while a product of another supplier stays unaffected](following-a-question-through-the-graph.svg){ class="bordered" } + +A new source connects instead of becoming another island. +A fourth system attaches to things that already exist. +It does not arrive as another table that nobody has joined yet. + +The meaning travels with the data. +A graph records not only that two things are related but what the relation means. +That is what allows a result to be explained, checked and reused, rather than only produced. + +## Identifiers do not disappear + +A common worry is that connecting systems means overwriting what they contain. + +The opposite happens. +The same product may be `P-10045` in one system, `PRD_10045_A` in a second and `45100-XX` in a third. +In a knowledge graph these become properties of one product. +Each fact can be traced back to the system it came from, and written back to it where that makes sense. + +![Product 10045 with its three identifiers P-10045, PRD_10045_A and 45100-XX, each recorded as a property that names the system it comes from](one-product-three-identifiers.svg){ class="bordered" } + +## What a knowledge graph is not + +Not a replacement for existing systems. +The source systems keep running and keep their data. +A graph adds the layer where their contents are related to one another. + +Not a data warehouse or a reporting tool. +A warehouse is built to aggregate numbers for known reports. +A graph is built to represent meaning and to answer questions that were not foreseen. + +Not automatic. +The relationships have to be stated deliberately. +That work is what the [Build](../../build/index.md) part of Corporate Memory is for, and it is the reason the result can be trusted later. + +## Where the terminology comes from + +Knowledge graphs are built on a set of open standards, usually grouped under the term Semantic Web. +Those standards are why words such as triple, IRI and vocabulary appear in this documentation. + +None of them are needed here. +The optional [Semantic Web basics](../semantic-web-basics/index.md) introduce them and show what each one looks like in Corporate Memory. + +## Next + +- [Semantic Web basics](../semantic-web-basics/index.md): optional, the terminology, about 35 minutes +- [eccenca Corporate Memory at a glance](../corporate-memory-at-a-glance/index.md): the parts of the product and how they relate diff --git a/docs/introduction/what-is-a-knowledge-graph/one-product-three-identifiers.svg b/docs/introduction/what-is-a-knowledge-graph/one-product-three-identifiers.svg new file mode 100644 index 000000000..510229bbd --- /dev/null +++ b/docs/introduction/what-is-a-knowledge-graph/one-product-three-identifiers.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + ID in the ERP system + ID in the PLM system + ID in the supplier portal + + + + Product 10045 + + + + + + + + P-10045 + PRD_10045_A + 45100-XX + + diff --git a/docs/introduction/what-is-a-knowledge-graph/things-and-named-relationships.svg b/docs/introduction/what-is-a-knowledge-graph/things-and-named-relationships.svg new file mode 100644 index 000000000..9e7c797f2 --- /dev/null +++ b/docs/introduction/what-is-a-knowledge-graph/things-and-named-relationships.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + is made at + is supplied by + + + + + + + + Product 10045 + Plant Leipzig + Kessler GmbH + + diff --git a/docs/three-systems-one-product.png b/docs/three-systems-one-product.png new file mode 100644 index 000000000..83c3e10bb Binary files /dev/null and b/docs/three-systems-one-product.png differ diff --git a/docs/video-corporate-memory-in-3-minutes.jpg b/docs/video-corporate-memory-in-3-minutes.jpg new file mode 100644 index 000000000..a4cb01a85 Binary files /dev/null and b/docs/video-corporate-memory-in-3-minutes.jpg differ diff --git a/nav.yml b/nav.yml index 5a9fdb8bf..abaf3b7df 100644 --- a/nav.yml +++ b/nav.yml @@ -3,6 +3,18 @@ # Do not edit by hand - run `task update:navigation` instead. # yamllint disable rule:line-length nav: + - Home: + - index.md + - What is a knowledge graph?: + - introduction/what-is-a-knowledge-graph/index.md + - Semantic Web basics: + - introduction/semantic-web-basics/index.md + - At a glance: + - introduction/corporate-memory-at-a-glance/index.md + - Get access: + - introduction/get-access/index.md + - See it in the product: + - introduction/see-it-in-the-product/index.md - Build: - Build: build/index.md - Introduction to the User Interface: