Graphs in the console¶
The concept behind knowledge is explained in Knowledge.
A graph holds the entities your documents are about, such as companies, people and products, and the relations between them. A schema you draw yourself decides which kinds exist. The Graphs segment of the Knowledge section is where you create a graph, edit its schema, view and add facts, have it filled from your collections and query it.
The list of graphs sits on the left and the one you picked on the right. Search above the list to narrow it, and use the plus to create one.
You need an administrator account of the organisation, and the knowledge capability has to be on
in the organisation's ceiling. You do the same with a key in
Graphs through the API.
Add a graph¶
Select the plus above the list. The Add graph drawer asks for:
| Field | What you enter |
|---|---|
| Name | unique within the organisation. Policy names the graph by this name, so it cannot change later |
| Description | what the graph is about |
| Labels | your organisation's own classification (below) |
| Metadata | optional. Your own key and value pairs, which no rule reads |
| Who sees which facts | Shared or Per person |
Who sees which facts cannot be changed once the graph is created:
- Shared draws in only sources that belong to nobody in person; everyone who reads the graph sees everything in it. This is preselected. Use it for the organisation's own knowledge, such as a product catalogue or a supplier register.
- Per person draws in every source; a person sees a fact only when one of the sources behind it is visible to her. Use it for documents that belong to people.
After Add the graph opens. It has no schema yet, and until there is a schema nothing can be written into it.
A graph's screen¶
At the top are the name, the description, the visibility and the buttons Query and Read again. You edit the description where it stands. Below that, from top to bottom:
| Part | What you do there |
|---|---|
| Labels | classify the graph for policy |
| Metadata | your own key and value pairs, which no rule reads |
| The Schema, Entities and Relations tabs | draw the schema, and view and add the facts |
| Collections | choose which collections the graph reads from |
| Ingest pipeline | the embedding model and the steps that read a source into facts |
| Sources read | the status per source |
| Run history | the runs in which sources were read again |
| Delete graph | delete the graph with all its schema versions and facts |
The description, the labels, the metadata, the collections, the embedding model and the pipeline choice are saved together: as soon as something has changed, a bar with Save appears. The schema has a button of its own, Save schema.
Draw the schema¶
The Schema tab is a canvas. Entity types are blocks, relation types the lines between them.
- Select Add entity type. A block appears.
- Click the block. Under Details you enter the name, the Type description and the Properties.
- Drag from one type to another to draw a relation, and give it a name and a description under Details.
- Select Save schema.
| Field under Details | What you enter |
|---|---|
| Name | what relations, keys and queries call this type, such as Company or supplies |
| Type description | what belongs under this type. An extraction model reads this to decide what belongs, so be precise |
| Properties | the properties the type has, as a JSON Schema |
| Identity keys | the properties that identify one entity of this type, chosen from the properties. Without keys the normalised name identifies it |
| From (entity types), To (entity types) | for a relation type: which types the relation may run between. The canvas draws one line per combination |
Remove type takes a type away. A relation type left without a start or an end by that goes with it; the screen says which. Reset layout places the blocks again. A schema has at most 50 entity types and 100 relation types.
Saving a schema that drops a type the graph still holds facts of is refused: the screen lists each such type with how many facts have it. Delete those facts first.
Versions¶
Every time you save a changed schema, a new version is created; the message names its number. When nothing had changed, no new version is made. The Schema version dropdown shows an older version. An old version is not changed in place: Edit from this version takes it as the starting point for a new one.
After a new version the screen says: what is already in the graph has not been re-checked and nothing has been read again. The next time sources are read, the new version applies. When you want that now, select Read again.
Have a schema suggested¶
Suggest schema has the organisation's helper model write a schema. Enter a description, choose a Collection as a sample, or do both. With a collection, the most recent sources you may read go to the helper model as data; Number of sources is 1 to 5, and each source is cut to 4,000 characters. When there are already types on the canvas, the suggestion changes those.
Make a suggestion shows the suggestion with an explanation, the number of types and the sources the model saw. Load onto the canvas replaces the drawing; nothing is stored until you select Save schema. Discard leaves the canvas as it was.
Which model the helper model is, you set on Settings.
Entities and relations¶
The Entities and Relations tabs show the facts in the graph. Filter by type, and search entities by name. The Origin column says where a fact comes from:
- Manual: someone wrote it here or through the API. You can edit and delete it.
- Extracted: it comes from a source. It is read-only, because the next time the sources are read it is replaced. Correct the source, or add a manual fact.
Add entity asks for a Type, a name, Aliases (other names, one per line) and the properties the schema describes for that type. Add relation asks for a Relation type and the From and To entities, which you search by name. Both buttons work only once a schema has been saved; for a relation the schema must have a relation type.
Open a fact to see its properties, which schema version it was checked against, and under Provenance the sources behind it. A source is a link to its collection. When it says there are no sources, the fact was written by hand or the source is not visible to you.
Deleting an entity also deletes the relations at its ends. Deleting a relation leaves the two entities.
Fill the graph from collections¶
Collections¶
Under Collections, tick the collections the graph reads from. Under a ticked collection is Filter: keys and values a source's metadata must carry. Leave the filter empty and the whole collection is read. A shared graph reads no source that belongs to a person.
Ingest pipeline¶
Under Ingest pipeline you choose two things:
- Embedding model: what the names of entities are embedded with, so a search also finds them by meaning. Empty is the installation's default.
- The pipeline: a built-in graph template, or an ingest pipeline of your own that ends in the Graph Store step. Without a pipeline the graph reads no source.
When you choose the template that extracts with a model, the screen asks for an Extraction model: the chat model that reads the entities and relations from each piece of text. The graph then gets its own copy of the pipeline with that model in it; you can save only once the model is chosen. The templates that read from metadata or from tables use no model. Their mapping is an example: adapt it to your schema with Edit ingest steps (Editing the steps).
Below it is the drawing of the steps. When the pipeline does not end in Graph Store, the warning No Graph Store is shown: nothing then enters the graph, and Core refuses such a pipeline.
Sources read, and reading again¶
Sources read shows per source the collection, the status (Queued, Working, Ready or Failed), the number of Facts, an error code and the moment of the last change. Search by title or filter by status. The title is a link to the source in its collection. A source that is Ready with zero facts names nothing the schema knows.
A new source in a ticked collection is read by itself. In these cases you read again yourself:
| What you did | What you do |
|---|---|
| changed the Embedding model or the pipeline | the screen shows the Read again notice with a button |
| saved a new schema version | Read again at the top right |
| ticked a collection that already held sources, or changed a filter | Read again at the top right |
| removed the cause of failed sources | Retry failed above the list of sources |
Read again reads every source in scope again. While a run is under way, a Reading sources bar counts along by itself. Run history shows the runs with their progress and trigger.
Extraction with a model costs model tokens for every chunk of every source, and again every time you read again. That usage is on Usage.
Query the graph¶
Query opens the query panel. A query is a form, not text: you start from entities of a type and follow up to three relations. The answer is the paths that can be walked that way.
- Under Start, choose a type, and optionally a name. Without a name the query starts from all entities of the type.
- Select Add step and fill in the Relation, the Direction (out, in or both) and optionally To type. Add up to three steps.
- Set Most paths and select Run.
The result shows the number of paths and entities, a drawing of the part of the graph the query reached, and the Paths list. With many entities the drawing shows only the first; the list of paths is complete. When it says the answer is partial, a limit per step or the maximum number of paths cut it short: make the query narrower.
A model does not query a graph here but through a search tool whose pipeline has a graph as a source. Create one from a template and choose the graph there; the search tool's screen then lists the graph under Sources.
Delete a graph¶
Select Delete under Delete graph. This deletes the graph, all its schema versions, entities and relations, and cannot be undone. The collections and their sources stay. Update search tools that read the graph before you delete it.
Labels¶
Use Labels to classify graphs. Rules about Knowledge graphs in a key's policy decide by name or by label which graphs that key, and a person, reaches (Rules about a person). The default rules permit every graph. See also Build for people.
Empty lists and access restrictions¶
When the left side is empty, this organisation has no graphs.
If knowledge is disabled, Index and search knowledge sources is off in the organisation's ceiling. The administrator of the organisation above turns it on under Permitted capabilities on Settings; for an organisation with none above it, your operator does.