Making a request

Although we advise using the Data Graphs Client SDK to access your data, you can query the API directly. In this case, you will need to combine the Base URL –&nbsp; 
	<code>https://api.datagraphs.io/</code>&nbsp;– with the relevant endpoint.
	<code>GET</code>, <code>POST</code>,&nbsp;<code>PUT</code>,&nbsp;<code>PATCH</code>, and <code>DELETE</code>&nbsp;methods are available.&nbsp;<code>GET</code>&nbsp;requests can include <a href="https://support.datagraphs.io/knowledge-base/using-data-graphs-api/query-parameter-reference">query parameters</a> that limit the size, ask for specific page, filter and sort the data in the responses.&nbsp;<code>POST</code>,&nbsp;<code>PUT</code>&nbsp;and&nbsp;<code>PATCH</code>&nbsp;requests require a JSON body.
	 The 
	<a href="https://support.datagraphs.io/api-docs/overview">API documentation</a> has more information, as well as sample requests/responses and a test harness for each endpoint.<h2>Headers</h2>
	 All requests require an&nbsp;API key&nbsp;and those to private Datasets must also include&nbsp;an&nbsp;OAuth 2.0 access token.
	API key –&nbsp;should be used as an&nbsp;&nbsp; <code>x-api-key</code>&nbsp;header
	OAuth 2.0 access token&nbsp;– should be used in the&nbsp;Authorization&nbsp;header as a Bearer token
	 See 
	<a href="https://support.datagraphs.io/knowledge-base/using-data-graphs-api/authentication">Authentication</a> for information on how to access your API key and generate an access token.

Creating a Knowledge Graph

Get started

What is a Dataset?

A Dataset is a namespace or bucket for collecting or grouping Concepts (entities) together.Once you have designed a domain model, you are able to create Datasets to hold your graph data.Data Graphs&#39; project homepage shows all the project&#39;s Datasets as cards where you can see the number and types of Concepts each Dataset contains.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/606c6fa98996210f18bd0740/file-T1XEAorhC7.png" alt="" style="float: left; width: 349px; margin: 0px 10px 10px 0px;">Datasets provide two main functions:1. Information management - a way to efficiently or conveniently manage data2. Security - a way to make some of your data public or privately accessible to applications at integration time<h2>Information management</h2>A Dataset does not add any semantic value to your knowledge graph, but does provide a nice way for you to group data together to improve its manageability.For example, you may wish to put all Concepts of one type into its own Dataset, such that a Dataset of Organizations would all be collected together. Alternatively you may have defined a Person type and create one Dataset to hold all politicians and another Dataset to hold all sports people.* Remember - you can still federate across all your Datasets. Putting the same type of Concepts into multiple datasets does not prevent you from searching and navigating data by type across your entire knowledge graph.<h2>Security</h2>A Dataset can be declared as public or private. This defines how the data within the Dataset is accessed by the Data Graphs API. Private - A Dataset declared as private requires the use of OpenID credentials. This means your data in this Dataset is secure and can only be accessed via an authenticated user request. Machine-2-Machine OpenID / OAuth credentials can be setup in the Application section of the project management settings. Private is the default option.Public - A Dataset declared as public can be accessed using just your API key. These data requests can be made without authentication.

Creating a Dataset

To create a Dataset click on the Create New Dataset tile on your current project&#39;s <a href="https://app.datagraphs.io/_account/_project">datasets page</a>. You will be to select the classes of Concepts you want your Dataset to contain. Each Dataset can hold concepts for as many classes of things in your domain as you wish.The Dataset has no semantic value, but is important in how you organize and manage your data.Typically you may name your Dataset after the types of things you want to store inside it. You can store all or just a subset of your graph data in each Dataset. For example if you have a class <code class="inline-code">Person</code> you might define a Dataset called <code class="inline-code">People</code> and store all the instances of Person inside. The other key benefits of Datasets is privacy and data security. A Dataset can be public or private, and this determines access rights to the data within via the Data Graphs API. A public Dataset can be queried and accessed just using an API key. A private Dataset can only be accessed with full machine-2-machine oAuth authentication.<h2>Step 1: Dataset settings</h2>Choose an appropriate name for the Dataset, an example would be to name it after the collection of Concepts that it will contain. You need to name it unambiguously. The namespace for the Dataset is a URN and is set automatically – urn:test:countries in the example below. The namespace is also important as this will be used as part of the API endpoint URL if you want to access this Dataset via the API.Choose whether the Dataset is public or private with respect to API access. A public Dataset can be accessed using the API from any client on the internet using an API key. A private Dataset can only be accessed using the API with OAuth / OpenID authentication. When you are happy with the main settings, click Add Types to configure the Concept types you want the Dataset to contain.<h2>Step 2: Adding classes</h2>Next you must add one or more types of Concepts that you want to include in the Dataset. We call this the Dataset Schema. You don&#39;t have to be exhaustive at this point as you can edit your schema at any stage before you add your data.Choose the first type you want to add, either selecting a type you have already defined or one of Data Graphs&#39; own types, or create a brand new type. In the example below we are naming a new type Country as we want to include Country Concepts in the Dataset. When happy, click the Add Type button.<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/644a35b040ac037159fb1a5a/file-5zbj2GTBqS.png" style="width: 100%; max-width: 100%; " />

Concept Classes

Every Concept in your Data Graphs account is assigned a type or class by you. The class or type describes the semantics of the class of Concept (such as Person, Animal, Organisation, Football Team etc). 
<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/607444244466ce6ddc5f397b/file-XWmWcDtME9.png" style="width: 329px; float: left; margin: 0px 10px 10px 0px;" alt="">The&nbsp;Concept&nbsp;class confers characteristics upon your data. It also enables you to query, navigate and facet data by class. For example, in the federated search screen there is a class facet presented by default – as shown in the screenshot.
This class facet shows how many Concepts of each type exist in your Datasets, entire knowledge graph or reference data.By selecting one of the types you can restrict the search results to only Concepts of that type, regardless of which Dataset the Concepts might be present in.<h2>Concept relationships</h2>Concept types are used when creating a property that references or links to another Concept in your domain model. If you specify a specific type in this relationship, Data Graphs understands the range semantics of the relationship and is able to validate and constrain the Concept editor to only allow Concepts of the type you selected.<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60745c91f8c0ef2d98df1693/file-rVOKHCiv9r.png" style="width: 565px; max-width: 100%; " /><h2>Managing Concept classes</h2>While you can view and manage Concept classes that exist within each Dataset schema, you can also create and manage classes using the dedicated domain modelling tool accessible from the main account menu called Domain Model. You can visualize the class hierarchy listing the classes across all your Datasets and model.You can delete an unused Concept type from right hand side bar of the Manage Types screen:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60745b618996210f18bd25f6/file-Dk9XGAnvLR.png" style="width: 100%; max-width: 100%; " />

Subclassing and Inheritance

Sometimes the Concept type you want to give your data shares a common pattern with other types. In Data Graphs it is possible to make types that share some common parent type. This is sometimes referred to as classes being a subclass of another class.This allows you to share common properties from the parent class and to facet on the child and parent class simultaneously.
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608134c68af76a714bfd9c82/file-OXyBuqMoUc.png" style="width: 254px; float: left; margin: 0px 10px 10px 0px;" alt="">For example, you might have a Vehicle Concept type that has properties for name and manufacturer. You could then define more specific&nbsp;Concept&nbsp;types for planes and motor vehicles. These might have their own set of specific properties – wing length for planes or transmission type for motor vehicles – but they will inherit the properties of the Vehicle&nbsp;Concept&nbsp;type as well.In addition, when you search for anything made by a manufacturer, your results will show any type of vehicle – plane or motor vehicle.<h2> Planning your Concept type hierarchy</h2>If you have already designed your model, it is useful to define Concept types related by subclassing and inheritance in Data Graphs from the top down. Start with the parent type and work down to define more specific Concept types. When it comes to creating a new type it is as simple as selecting from the existing parent types in the drop down list. By defining your parent types first they will be available to select when it comes to defining more specific Concept types.<h2>Creating subclasses</h2>You create a subclass when creating a Concept type schema in a Dataset. You can do this in one of two ways:<ol><li>Using the domain modelling tool you can connect a child class to a parent class visually to create a subclass relationship</li></ol><img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/644b83d921e70872064dfafa/file-YWPIGl7z2p.png" style="width: 49.73%; max-width: 100%; " /><ol start="2" ><li>After naming your Concept, you have the option of choosing a Parent Type for the Concept you are defining.</li></ol><img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608675bef8c0ef2d98df609a/file-AL51K2sLxl.png" style="max-width: 100%; " />By selecting the Include parent properties option, your new subclass will inherit (re-use) the properties from the parent class. This is most likely what you will need to.<h2>Managing classes</h2>The Class Explorer screen allows you to see a visual representation of your current type hierarchy. This view is accessible by selecting Class Explorer button in the domain modelling tool. Within this screen you can remove a type that you no longer require or have created incorrectly in your type hierarchy.
	<img src="https://lh6.googleusercontent.com/AqGXF5eT55DyiGM8rAvynSRwGGUCbhxm4YScCESUXUXS7__56-YULmFBSwm2OOW8BwmRyhNZm8NWGS0Wi926G3XcZo3Irfgm-JPSF_UjmgIJfs3ZVHiBvSqaofO9HZqrmAS1y70U" style="margin-top: 0px; margin-left: 0px;" width="624" height="289"><h2>Transitive class inference</h2>When you create a subclass type, Concept relationships become class-structure aware, with transitive inference. When a Concept property defines a relationship to another Concept type/class, Data Graphs allows you to select Concept instances of that type and all its subclasses. For example, if you create a class FootballTeam that is a sub-class of Organization, and you then create a property on another Concept of type Organization, transitive inference means that football teams can be assigned to that property as well as organizations. Search facets and API queries also obey the semantics of transitive inference across a class hierarchy.<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608678378af76a714bfdad60/file-x7YinLI0un.png" style="max-width: 100%; " />

Data Types

When you create a Dataset and define a new Concept you define the properties for the Concept. Each of these properties has a data type. The data types fall into 3 main categories:<h2>1. Primitive data types</h2>These are fundamental data types for value-based properties. The different primitive data types are:<ul><li>text – a string of characters or words. Used for labels and descriptions etc. All text properties are indexed for full text search. The primary label of a Concept is boosted for full text searching.</li><li>keyword – a contiguous character string with no whitespace. A keyword is not indexed for full text search, but instead is used for identifiers or terms that can be queried as an exact match. You may use these, for example, for representing an alternative identifier, an ISO code, or a passport number.</li><li>integer – decimal integers only, no whitespace, e.g.  65432</li><li>decimal – a decimal value, no whitespace, e.g. 12.34567</li><li>boolean – a boolean value, true or false</li><li>date – an ISO-8601 date, YYYY-MM-DD,  e.g.  2021-04-17</li><li>dateTime – an ISO-8601 dateTime, YYYY-MM-DDThh:mm:ssZ  e.g. 2021-04-17T13:14:32Z. A timezone component can be included.</li></ul><h2>2. Specialised primitives</h2>These are also primitive data types for value type properties, but can be interpreted for specific use-cases in Data Graphs :<ul><li>latitude – a decimal field for capturing geospatial latitude coordinate values. When combined with a longitude Data Graphs indexes these properties for geospatial search, and also allows your Concepts to be plotted on a map.</li><li>longitude – a decimal field for capturing geospatial latitude coordinate values. When combined with a latitude Data Graphs indexes these properties for geospatial search, and also allows your Concepts to be plotted on a map.</li><li>geohash - a single field for identifying a geospatial location of a concept.</li><li>URL – interpreted and validated as a URL</li><li>imageURL – interpreted and validated as an image URL, and can be set as a canonical preview image of the Concept. Properties defined as imageURLs are rendered as images in Data Graphs.</li><li>videoURL - interpreted and validated as a video URL. Properties defined with this type can be played as video directly in the Data Graphs UI.</li></ul><h2>3. Relationship properties</h2>You can select any other previously defined Concept type as a value of some property. This allows you to define semantic relationships between things in Data Graphs, and lends itself to the knowledge graph or linked data pattern. When you select a specific Concept type as the data type of some property, Data Graphs is able to validate and constrain the allowed Concept value to be only of this type. If you have utilised sub-classing, and the property range is some parent class Concept type, then Data Graphs will constrain the range of the relationship to include all Concepts of the parent class selected and the set of all sub-classes of this Concept type.

What is a Concept?

A Concept is an instance of some thing in your domain. Concepts are the instance data that you populate your knowledge graph or reference data set with. People, places, organisations, tangibles and intangibles that are of relevance to you, your business, or your projects are all&nbsp;Concepts.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/607168f28996210f18bd201c/file-13qZsU4TsY.png" style="width: 401px; display: block; margin: auto;" alt="Concepts are the instances of things in your domain">
	 In Data Graphs, a Concept has a schema that defines its type (class), its properties and relationships to other&nbsp;Concepts.
	 When you create a Dataset you define the types of&nbsp;Concepts&nbsp;you want to populate it with. At this point you are able to:<ul>
	
<li>select or re-use Concept types you have already defined</li>	
<li>define new Concept types</li>	
<li>update the properties of an existing Concept type</li></ul>
	 All&nbsp;Concepts&nbsp;have an id and a label&nbsp;as fundamental properties. As a user you define whether you want to supply your own the ids (Manual&nbsp;Identifiers) or allow Data Graphs to generate them (Automatic Identifiers).&nbsp;
	 All other properties of a&nbsp;Concept&nbsp;are defined by you.
	 There are several ways of ingesting and maintaining&nbsp;Concepts&nbsp;in Data Graphs :<ul>
	
<li>Import Concepts in bulk into a Dataset using the CSV import wizard&nbsp;</li>	
<li>Import Concepts via the Data Graphs API</li>	
<li>Manually create and update Concepts using the Data Graphs user interface</li></ul>

Importing Data

Data Graphs lets you import data in tabular form using CSV files with a user interface where you can map CSV columns to your Dataset and&nbsp;Concept&nbsp;schemas.
	 The key steps in importing data are:<ol>
	
<li>Prepare a CSV file with the data you want to import, with each row representing one Concept or entity in your Data Graphs Dataset</li>	
<li>Create a Concept schema in a Dataset where Concept properties can be mapped to the data in your CSV column</li>	
<li>Use the Import Data wizard in a Dataset to guide you though mapping different CSV columns to the correct Concept properties</li></ol>
	 Key points:<ul>
	
<li>Your CSV does not need column headers, but this can help</li>	
<li>Column headers do not need to match the property names in the Concept schema, but if they do, Data Graphs will match them automatically. If they do not, you can match them yourself</li>	
<li>Each row in the CSV represents one Concept in Data Graphs, but you can import rows from one CSV file into multiple Concept types if you have a column in the CSV that identifies the Concept type of the row (eg Person, Organization etc)</li>	
<li>If the Concepts being imported are configured in Data Graphs&nbsp;to have manual identifiers, one of the columns in the CSV must hold the identifiers. With automatic identifiers, no identifier column is required</li>	
<li>You can match columns to relationship properties if the column contains identifiers of Concepts that you have either already imported or are planning to import.</li>	
<li>Data Graphs allows for "eventual consistency"&nbsp;– you can import links to other Concepts either before or after the linked Concepts are imported.</li>	
<li>Importing handles subclassing. If you import linked data where the target (linked) Concepts are of subclasses of the relationship you can either choose the type of linked Concept when you map your columns, or use a different column in the CSV as a type discriminator.</li><li>Maximum file size is 10MB. Larger files should be split and imported separately.</li></ul><h2>Importing a simple CSV</h2>
	 The following example demonstrates how to import a simple CSV where all the rows are mapped to a single&nbsp;Concept&nbsp;type. In this example we import a CSV of countries, where each row represents one Country, and the identifiers are the 2-character ISO codes.<h3>Step 1: Prepare the CSV and schema, and upload the file</h3>
	 Our CSV is structured as follows:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608eb124f8c0ef2d98df874f/file-tNCQli5DQ3.png">
	We have a Countries&nbsp;Dataset&nbsp;containing a&nbsp;Country&nbsp;type:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608ec6333149d33a19c72c58/file-ErQ9B33iJI.png">
	 Now upload your CSV using the file uploader, select your CSV file and click the import/upload button:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608ec65ae0324b5fdfd10f0f/file-V5ux0nkp0e.png"><h3>Step 2: Check the CSV headers</h3>
	 Data Graphs asks you if the CSV has a header row – choose 
	Yes or No:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608ec6b08996210f18bd9698/file-ZImjW4Bfdh.png"><h3>Step 3: Map the columns to Concept properties</h3>
	 For each property of our Country&nbsp;Concept, choose the CSV column that matches it. Data Graphs will attempt to match those columns that have the same names, but if not you can choose the correct column. Data Graphs will tell you how many rows have value data and flag up any potential data issues. When you have selected the column, choose the 
	Confirm option. You can also ignore a column in the CSV if you wish.
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608ec8413149d33a19c72c5a/file-J5X5P5QWi4.png"><h3>Step 4: Review your data and import</h3>
	 When you have mapped all your columns to properties, you can review the data you are importing. If you have made a mistake, you can go back to the previous steps and adjust. If you think you need to start again and adjust your CSV for data quality, you can still cancel, as nothing has been stored yet.&nbsp;
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608ee2ba8af76a714bfdd3bd/file-QXyjhaD5JG.png">
	 When you've finished reviewing the data, click the Import button. The data will be uploaded to Data Graphs, processed and loaded into your&nbsp;Dataset. This ingest is done asynchronously, so if it is a very large import, you can safely close your browser and come back later. Progress will be reported.
	 Once imported you can view your data, for example:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608ee29d3149d33a19c72c70/file-P2m5NUv8qA.png">

Search Facets

In addition to free text search Data Graphs provides search (filter) by facets – properties that have been defined for a&nbsp;Concept&nbsp;type. For example, an aircraft might be associated with a manufacturer or a football players might be associated with a team. Faceted search allows you to combine a free text search with filtering based on a Concept's properties.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60813fe18af76a714bfd9cb6/file-byAZMOWnBq.png" style="width: 212px; float: left; margin: 0px 10px 10px 0px;" alt="">
	 Facets can be found on the left hand side of the search results screen. The default list of facets is always the&nbsp;Concept&nbsp;types. You can filter on any property you have defined as part of your schema. The additional facets can be found in the more facets dropdown.
	 When a facet is selected, the current set of&nbsp;Concepts are filtered to show only those that match that facet and any other existing search criteria. Counts of matching&nbsp;Concepts are provided based on the what is currently returned with facets and search terms applied.&nbsp;
	 Faceting by&nbsp;Concept&nbsp;label is included for data quality purposes as it is useful to see where there is more than one&nbsp;Concept&nbsp;with the same label.Faceting on a property that is inherited from a parent type will work across all the&nbsp;Concept&nbsp;types that it inherit from it. For more information see <a href="https://support.datagraphs.io/knowledge-base/managing-data/subclassing-and-inheritance">Subclassing and inheritance</a>.

Viewing and Modifying a Dataset Schema

Once you have created a Dataset you may need to modify its schema, either to add new Concept types to it, or to modify the properties of a Concept within.To view a Dataset&#39;s schema, click the menu icon in the top right of its tile on the relevant project&#39;s homepage, and select Manage.<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/607427b34466ce6ddc5f38cf/file-13fMnlmRGa.png" style="width: 631px; max-width: 100%; " />This will take you to the Dataset&#39;s Schema screen – a read-only view of the its Concepts and their property definitions:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/644b8311d50b2033bd241931/file-LImVSx2sVT.png" style="max-width: 100%; " /><h2>Adding a new Concept class to a Dataset</h2>To add a new Concept class/type to a Dataset schema, click on the Manage button at the top of the read only schema view. Then select one or more new Concept class to add (or remove) from the Dataset<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/644b8359cdec2a7348811db8/file-Np5kYkPB4P.png" style="max-width: 100%; " />

Identifiers

Understanding how Data Graphs utilises identifiers is critical to understanding how to best setup your Datasets and maintain your data.<h2>Key points</h2><ul><li>Every Concept (entity) in Data Graphs has an identifier</li><li>The identifier is unique to the class (type) of Concept, for example all Concepts of type Person must have a unique identifier within the scope of all Person Concepts in your Data Graphs project.</li><li>When you create a concept in the UI the identifier field is blank. You can:<ul><li>provide an identifier of you choice</li><li>click the gear icon next t the field to generate one</li><li>leave it empty, and Data Graphs will generate an ID automatically when you save the concept</li></ul></li></ul><h2>URNs</h2>Internally Data Graphs uses URNs to namespace identifiers by Concept type. A URN is like a URI but is not web resolvable. The URN pattern used in Data Graphs is <code class="inline-code">urn:{project}:{type}:{id}</code> for example <code class="inline-code">urn:test:Person:1a2b3c4d</code> . You will see these URNs when viewing Concept data. In most circumstances you need not worry about using URNs, especially in the Data Graphs app or when importing data – you can just use the identifier on the end part of the URN. But if you are using the API to query data, the URNs are important as they provide the true identity of each concept.<h2>Manual / Custom identifiers</h2>If when designing your domain model you choose a custom property to be the identifier then Data Graphs cannot generate one for you, and it becomes mandatory you supply these identifiers yourself. Why might you choose manual IDs?  A good example is when you might be importing some external data that already has unique IDs. Or there might be a particular ID pattern you need to use, e.g., the 2 or 3 character ISO-3166 codes for identifying countries:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608f00328af76a714bfdd3e5/file-1w4ijrFwpN.png" style="max-width: 100%; " />

Creating a Domain Model

Auto-Generating a Concept Label

Data Graphs allows you to generate a concept’s label automatically from other properties, which can save time when it needs to follow a pattern, eg: <code class="inline-code">{user.name} - {customType.label} - {date}</code><h2>Enabling label auto-generation</h2>To enable this feature, select the relevant Concept in the Domain Model editor and turn on the Auto Generate switch on its label property:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/673c842307276709d1e57131/file-s6ogZnAbRn.png" style="width: 318px; max-width: 100%; " />With the toggle turned on, the Auto Generate input will appear:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/673c843a268fb643f63a5b53/file-WCKoOOfz5V.png" style="max-width: 100%; " />Enter a pattern here that describes how to formulate the label, and save the model. Now when you create a Concept and populate the fields referenced in the pattern, the label will populate at the same time.<h2>Label auto-generation patterns</h2>There are various ways to use patterns to generate a Concept’s label using curly bracket syntax. <h3>1) Simple property</h3>The simplest way is to use the value of a property and some text, eg:<code class="inline-code">This is a {property1} concept</code> The value can be a text, number or time datatype. There is no limit to the number of property references you can use.<h3>2) Nested or related property</h3>You can do the same thing with a nested or related property, perhaps a user field of type User which has firstName and lastName properties. In this case:<code class="inline-code">This is {user.firstName} {user.lastName}’s concept</code> Note: auto-generating labels only works on one level of nesting.<h3>3) Excel formulas</h3>Data Graphs uses Excel-type formulas that allow you to generate labels from logical expressions.The formulas available are:<code class="inline-code">CONCATENATE</code> <code class="inline-code">IF</code> <code class="inline-code">SUM</code> <code class="inline-code">TEXTJOIN</code> <code class="inline-code">ISBLANK</code> Formulas should appear in an expression within double curly brackets. Property names still appear within single brackets. Examples:<code class="inline-code">{{CONCATENATE({firstName},&quot; &quot;,{lastName})}}</code> Joins the values together, in this case the names are separated by a space.<code class="inline-code">{{TEXTJOIN(&quot;, &quot;,true,{prop1})}} </code> Uses the delimiter in the first argument to join an array passed as the third argument. The second argument determines whether to ignore empty values.   <code class="inline-code">{{IF({prop1}, {prop2}, {prop3})}}</code> Uses the value of the first to determine the value returned. In this case if prop1 is true, prop2 is returned. If it is false, prop3 is returned.<code class="inline-code">{{IF(ISBLANK({prop1}),{prop2},{prop3})}}</code> In this case using <code class="inline-code">ISBLANK</code> creates the boolean required for the first argument of the IF statement.<code class="inline-code">{{SUM({prop1},{prop2},{prop3})}}</code> Adds arguments that are integers and/or decimals.

Language Tagged Strings

Data Graphs supports internationalized / language tagged strings - conforming to the RDF and ISO standards for lang tagged literals.To use lang tagged string literals, the datatype of the property must be set to <code class="inline-code">text</code> and the option for <code class="inline-code">Multiple Languages</code> turned on:<img alt="options for langage tagged strings" src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6486f70974c2142995f91b06/file-AdEp9xGjGU.png" style="width: 34.59%; max-width: 100%; " />When editing a concept or entity that has a text field configured for multiple languages, you get to choose the language code of the text you enter, choose which language string should be presented as the default, and optionally add additional strings for the same text field for other languages: <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6486f8417f8c2575e3544b73/file-4pTmu5988Z.png" style="width: 76.62%; max-width: 100%; " />When querying properties that have multiple languages via the API, the response conforms to the JSON-LD specification for language tagged string literals, for the above example, your JSON will look like:<div data-html-block><pre><code class="language-json">{
 "displayName": {
 "en": "house",
 "fr": "maison",
 "es": "casa",
 "de": "Haus",
 "@none": "house"
 },
 "type": "Building",
 "id": "urn:demo:Building:0TSINGXVpT3rQCxjnLJ9cs"
}
</code></pre></div> When using the API you can request data in all languages or a specified language using:<ul><li>a <code class="inline-code">lang</code> query parameter, passing the language code, or <code class="inline-code">*</code> for all languages</li><li>the Accept-Language request header with the language code or <code class="inline-code">*</code> as the value </li></ul>

Searching a Dataset

Data Graphs allows you to search within a specific Dataset or across all the Datasets in a given account, known as a&nbsp;"federated search".
	 The search box on a project home screen allows you to carry out a federated search. You do not have to specify a search term – you can perform an empty query that will return all data and allow you to navigate by facets. A free-text search can be added, as well as a filter by facet, at any stage and in any combination.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60813b37e0324b5fdfd0d85c/file-KFJq94QJUH.png" alt="Search across all datasets" style="display: block; margin: auto;">
	 To search within a specific Dataset and use&nbsp;its associated facets, select the Dataset from the project home screen and search from the sidebar on the subsequent Concepts screen. You can return to a federated search at any time by navigating to the home screen.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60813b833149d33a19c6f53e/file-acQALz2QAI.png" alt="Searching within a dataset" style="display: block; margin: auto;">
	 
	 See <a href="https://support.datagraphs.io/knowledge-base/managing-data/search-facets">searching by facets</a> for more information.

Merging Concepts

Sometimes you will want to take one or more Concepts and merge them into a single existing Concept. This might be because of data errors that created duplicate Concepts or because you now consider the Concepts to be the same.
	 To merge Concepts, select two concepts from any Concepts list or search results screen:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608146a13149d33a19c6f58b/file-wkvA2EcUnG.png" style="width: 648px;">
	 And then choose Merge Selected&nbsp;from the menu in the bottom right corner of the screen.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6102806d64a230081ba1a1b2/file-uGW04E8hq3.png" style="width: 193px;">
	 The next screen allows you to decide which is the target concept, which you will retain, and which is the source concept, which will be merged into the target. &nbsp;You can swap&nbsp;between the two of them using the button at the top. Note that the id of the target concept will be retained and used as the canonical ID for the merged concept.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60814743f8c0ef2d98df5059/file-cr6cmfiNMZ.png">
	 You can copy fields from the source to the target concept by clicking the arrows. The lock icon indicates that the field is not editable at the merge stage but you can still copy and the value to the target concept.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608147a18996210f18bd5f02/file-0fUJNyeVlf.png" style="width: 345px;">
	 When you have decided what data is to be retained, you can confirm the merge of concepts.

Deleting Concepts

A Concept can be deleted individually or as a group.
	 To delete an individual Concept, select it and enter the "Concept view" screen. Then in the left-hand menu, select Remove Concept.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6081445af8c0ef2d98df5049/file-VXmkNcM0AX.png" style="width: 302px; float: left; margin: 0px 10px 10px 0px; clear: both;" alt="">
	 To delete groups of Concepts from any list view or search results screen, you can select multiple Concepts via the check box on each Concept.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6081447f3149d33a19c6f576/file-Xf6o3MQ80U.png" style="width: 252px;" alt="">
	 Then in the bottom right of the screen, you can open the menu to choose to Delete Selected.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61027f0eb37d837a3d0dea2e/file-gbc6UwiRAw.png" style="width: 251px;">

Advanced Search

This feature allows you to build complex queries to search for Concepts within a given Dataset by chaining and grouping boolean expressions.&nbsp;You will find it on the Concepts screen and can access it by clicking the three dots icon at the top of the sidebar and selecting Advanced Search:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/62e3c0b7a3bd51396505487f/file-fET4UcQYVC.png">Building a Query
	 Datagraphs' Advanced Search allows you build a series of boolean clauses (Items), each of which consists of a property type, a value and in some cases an operator or operator expression. Items can be chained&nbsp;together with boolean operators (AND, OR). It is also possible to describe a Group of items which can in turn be combined with other Items or Groups.<h2></h2>
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61b87313a5e184696a17a8a1/file-Qqts3byvFZ.png" style="width: 305px;"><h2>Searching with an Item</h2>
	 To create an Item, select a property and then choose or enter the value you wish to search for. In the example below the property is <code>Type</code> and the value is <code>Ingredient</code>, and clicking Search will find all Concepts whose Type is Ingredient.
<div style="display: flex;">
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61b873c0a5e184696a17a8a4/file-en47KHrEtm.png" style="width: 307px;">
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61b874d9e5e5185a647d47bd/file-Jpg6HsXl7B.png" style="width: 307px; margin-left: 40px;">
</div><h2>Searching with multiple Items</h2>
	 Clicking Add Item allows you to create another item. By default it is combined with the existing item with a boolean AND operator; in this case the query will return concepts that match&nbsp;all&nbsp;items in the group. Toggling the&nbsp;button on the left-hand bracket from&nbsp;ALL&nbsp;to ANY produces a boolean OR operator, meaning the query will return concepts that match&nbsp;any item in the group.
<div style="display: flex;">
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61b87844e5e5185a647d47c1/file-cTu8rGTiuX.png" style="width: 307px;">
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61b878daa5e184696a17a8b6/file-DS2k2F00js.png" style="width: 307px; margin-left: 40px;">
</div><h2> Searching with Groups and Items </h2>
	 With more complex queries, you can group Items by boolean operator. To create a Group, click Add Group and create its items as usual. The following example combines a Group with an item. But Groups can also be combined with other Groups, and can themselves contain a Group or several Groups.&nbsp;
<div style="display: flex;">
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61b87a9ba5e184696a17a8bf/file-5DbWo50ue6.png" style="width: 307px;">
	 
</div>

Exporting Search Results

You can export the results of any search query using the Export Results button:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/673c58891f08a96042003255/file-LjLBM58rpZ.png" style="width: 579px; max-width: 100%; " />By default, the export format is set to <code class="inline-code">.csv</code> , with column headings reflecting property names. Aside from the defaults (id, type, label), you can edit the names of the columns, remove columns and change how properties map to columns.<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/673c5a6f07276709d1e57108/file-dcgeo7gWzr.png" style="width: 573px; max-width: 100%; " /> You can also export results as <code class="inline-code">JSON Lines</code> , which you can preview before execution: <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/673c59e41f08a96042003256/file-sB9zn8eZHA.png" style="width: 569px; max-width: 100%; " /> All exports are available for download in the Data Graphs Exports page.

Custom Validation Rules

The custom validation rules are a configurable set of rules which can be applied to the majority of available property data types, providing an additional layer to ensure the logical integrity of your data. Validation rules can be a critical tool when using Data Graphs for master-data management or reference-data management.<h2>1. Custom Validation Rules</h2>
	 Basic Rules<ul>
	
<li>Custom RegEx&nbsp;- validates strings agains any valid&nbsp;regular expression. Can be applied to both keyword&nbsp;and text&nbsp;property data types.</li>	
<li>Min Characters - validates total number of characters, incl. whitespace,&nbsp;in a string against a specified number. The number of characters has to be greather than or equal to the specified number. Can be applied to both keyword&nbsp;and text&nbsp;property data types.</li>	
<li>Max Characters - validates total number of characters, incl. whitespace,&nbsp;in a string against a specified number. The number of characters has to be less than&nbsp;or equal to&nbsp;the specified number. Can be applied to both keyword&nbsp;and text&nbsp;property data types.</li>	
<li>Min Words - validates the total number of words in a string against a specified number. The number of words has to be greather than&nbsp;or equal to&nbsp;the specified number.&nbsp;Can be applied to text&nbsp;property data type.</li>	
<li>Max Words - validates the total number of words&nbsp;in a string against a specified number. The number of words has to be less than&nbsp;or equal to the specified number. Can be applied to text&nbsp;property data type.</li>	
<li>Min Value - validates numeric input against a specified value. The input number has to be greather than&nbsp;or equal to&nbsp;the specified value. Can be applied to integer, decimal, latitude&nbsp;and longitude&nbsp;property data types.</li>	
<li>Max Value&nbsp;- validates numeric&nbsp;input against a specified value. The input number has to be less than&nbsp;or equal to&nbsp;the specified value. Can be applied to integer, decimal, latitude&nbsp;and longitude property data types.</li>	
<li>After Date&nbsp;- validates input date against a specified date. The input date has to be&nbsp;AFTER&nbsp;the specified date. Can be applied to&nbsp;date&nbsp;and&nbsp;dateTime&nbsp;property data types.</li>	
<li>Before Date - validates input date against a specified date. The input date has to be BEFORE&nbsp;the specified date. Can be applied to date&nbsp;and dateTime&nbsp;property data types.</li></ul><h3>Special Rules</h3><ul>
	
<li>Must be in the past - validates input date against the a relative date. When creating a concept the input value has to be BEFORE&nbsp;the current time. When editing a concept the input value hast to be BEFORE&nbsp;the creation date of the concept.&nbsp;</li>	
<li>Must be in the future&nbsp;-&nbsp;validates input date against the a relative date. When creating a concept the input value has to be&nbsp;AFTER&nbsp;the current time. When editing a concept the input value hast to be&nbsp;AFTER the creation date of the concept.&nbsp;</li>	
<li>Min Items - validates the number of items in an array property against a specified number. The number of items must be greather than&nbsp;or equal to&nbsp;the specified number. Can be applied to ANY array property of&nbsp;ANY&nbsp;property data type.</li>	
<li>Max Items&nbsp;- validates the number of items in an array property against a specified number. The number of items must be less than&nbsp;or equal to&nbsp;the specified number. Can be applied to ANY&nbsp;array property of ANY&nbsp;property data type.</li></ul><h3> Unsupported Data Types</h3>
	 Boolean - a boolean is inherently only true or false, and thus no additional custom&nbsp;validation is necessary.
	 URL and ImageUrl&nbsp;- these can only be validated as a URL string,&nbsp;&nbsp;and thus no additional validation is necessary.<h5></h5><h2>2. Working with the validation rules</h2>
	 Custom validation rules can be added through the dataset creation wizzard, at the point when properties are being customised. You can also add or remove rules at any point after creating the Concept Type through the type schema editor.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/616d938d9ccf62287e5ece1e/file-g3cR8StJVR.png" style="background-color: initial;">
	 Your rules will be applied immediately and will be visible in the Concept form.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/616d95b99ccf62287e5ece31/file-ImOnxc7V8S.png"><h5></h5>

Federated Search

If you have multiple Datasets you can search across all your data and all your Concepts using a federated search.&nbsp;
	 You can start a federated search from the project homepage, where all its Datasets are listed, by typing into the search bar at the top of the page. This will let you select a Concept, or if you hit return it will invoke a detailed full text search.&nbsp;
	 &nbsp;Alternatively you can click the arrow button highlighted below without typing in the search bar:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61a0a1d8efc78d0553e5de20/file-xn1WxkuzCr.png">
	 In this case you will be presented with a search page that lets you facet across all your data and build a search from scratch:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61a0a2a6efc78d0553e5de23/file-leJHJXgqAa.png">

Property Inferencing

Data Graphs provides inferencing for both symmetric properties and inverse relationships. These are equivalent to <a href="https://www.w3.org/TR/owl-ref/#SymmetricProperty-def">owl:SymmetricProperty</a> and <a href="https://www.w3.org/TR/owl-ref/#inverseOf-def">owl:inverseOf</a> reasoning.Both of these inferences can be applied as attribute settings on relationship (Object) properties in the domain model editor:  <ul><li>Symmetric properties are set with Is Symmetric </li><li>Inverse properties are set with Is InverseOf </li></ul>These attributes can be added, edited or removed only if the Class being modified has no instance data associated with it.<h2>Symmetric Properties</h2>A symmetric property can only be added to a Class where the range of that property is the same Class or a subclass of it. The property should not be an inverseOf property.  To add a symmetric property, on a data property set the Is Symmetric attribute:<img src="https://lh5.googleusercontent.com/_N6ps6gG8f77J3NbklrPnXIzlHu489arQqQSZVbxTsNVAGf2nmhYM-PprJaq-YrhdLIBvjw3kg8eYHfrkw9FH4zn0xoNMZCU-4y8LUvBSE1h71liVBGONThjnYl-MR4FI3K-oTFX5mgiFWNvV8wxSP0" style="width: 71.89%; max-width: 100%; " /> When adding data for a Class that has a symmetric property, the inverse relationship will automatically be added (inferred) to the Concept instances referenced by this property. In the following example, Concept Jim has a symmetric property hasSpouse. Adding the Concept Jane to that property...<img src="https://lh5.googleusercontent.com/6y5chShNXcBi-XiMpdN1pbhatSCQhlMMrwcDIPZL1X8nPsvotkAF1Aw75VL63Ry1YBFz2eZInMFtjqAW17Uit1yeWpnyeQ48xHBAdEdSEmeCtJuWiMrSEUhcsCsQU9WxSsnx33WBoMPBm543lmcqfxk" style="width: 100%; max-width: 100%; " />… automatically adds hasSpouse -&gt; Jim to the Concept Jane:<img src="https://lh6.googleusercontent.com/9dv0BS4QppmbgwQlqXOtBtq6R82yKtlIZOev1X_lnXPrGFMASwj6fYYhCS0K5ovRlOVaRVyyIfs6l2kR1_gx2hjwxecWpY2mMkaPwFLV2PZLbgDcf3yIuM5i3uLDeFDcGW-JIOqx8mgcPqPlss4ELVY" style="width: 100%; max-width: 100%; " /><h2>Inverse Relationship Properties</h2>Inverse relationships can only be added to properties which share each other&#39;s classes as their range or subClass definition. In other words, an inverseOf relationship can be added to property A on Class A, where the range of property A is Class B whose own property (B) has a range of Class A or is a subclass of Class A.To add an inverse relationship property to an object property, select the property for the Class in range from the Is InverseOf dropdown. In the example below teaches, a property of Person, is selected as the inverse relationship of Subject -&gt; specialist: <img src="https://lh6.googleusercontent.com/Vlm7_Ji0voT2e-dwypVCuppDISos2sRqsQ612O7Ld1vo9vBqA7OqHnsKtFq-s_yMSYIlogujMpQG5weob9mAYeBsNqfbrZQy1e4fBNFsSnKH6Z7YDQU5dDYQ7T6VhMYy076JWU-QTOgvD1IlDqJMgpQ" style="width: 100%; max-width: 100%; " /> This step will also add the reciprocal inverse relationship to the referenced Class’s property, in this case specialist is automatically selected as Is InverseOf on Person -&gt; teaches.<img src="https://lh3.googleusercontent.com/oVVYFUYvz2cMp1Oe-Q-NKtGsa7EM-p8sb2mQ1jnRKmH8r2cP4ZgmfB7tUC7iH2RwCKOvUWrKM7-ZONMpKnauhvLhmIpwaG2qWT9_SzUk37GbyKb3cbe7l78OvVO7UXEVUS93qXKBfI9qvXEOnmihzgI" style="width: 100%; max-width: 100%; " /> When adding data to a property with an inverse relationship, the Is InverseOf property will also be inferred on the referenced Concept. In the example, adding Jane to the specialist property of the Concept Science…<img src="https://lh5.googleusercontent.com/EYk5vlGnF7NCFfTMfl4oaUqvULyAWb2YvDvDnOv9SP6K9pqEKv1XxQinfOrvDinRV-d1SS30eqdBKoBCiOr9mbVgQ5V4ZFgey5f9lOl7D9_tehi87mynTYUzMj_M-Z34TyE5kygOqGvVzUYhEOiGfOc" style="width: 100%; max-width: 100%; " />… means that Science is automatically added to the teaches property on the Concept Jane. <img src="https://lh6.googleusercontent.com/8XY1ylifkB1Bwkxw1Ulg2VAivX9sFNFAJS-OtdTjO4X4d-djrfWQRX2g7kGFj6IfB8yADlJCWJplH5oCztK3_CsH-llAwvjvdnJMSZSx5g7fGuIIdF3Qg0neOU1xKI0j1G8A01SArEbxJzUVf92LzCs" style="width: 100%; max-width: 100%; " />To remove an inverse relationship from a property, select the None option from the Is InverseOf dropdown. This will also remove the reciprocal relationship from the referenced inverseOf Class.

External Links

Data Graphs’ External Links feature allows you to create a URL pattern based on a given Class. This can be useful if a Concept created from the Class represents information used on a webpage. For example a Person class might correspond to a page about an actor or a musician, where the id of the concept is used to fetch the data.<h2>Creating an External Link</h2>To create an External Link, navigate to the corresponding page in the Manage Project section. Select the name of the Class you want to base your links on and then define the pattern. The pattern must include the name of a property (in curly brackets) whose value will appear in each link. In this example it is the property <code class="inline-code">id</code> , eg:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/673c63791f08a96042003261/file-EQu2FS2nAH.png" style="width: 100%; max-width: 100%; text-align: left;" /><h2>Using an External Link</h2>For every Concept you create or have created from that Class, Data Graphs will then generate a URL based on the pattern, which will be available as a link on the right hand side of each Concept: <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/673c6490253ee02cb10711b1/file-BRqX6CDFoI.png" style="width: 100%; max-width: 100%; text-align: left;" />

Importing and Exporting Domain Models

Data Graphs allows you to import and export a Domain Model in either Native JSON or RDF/OWL Turtle format.<h2>Importing a model</h2>To import a model navigate to the Domain Model area from the main menu and click Import Model. You will subsequently be asked to choose the format of the file you are importing and to either select the file or drag it into the uploader.<h2>Exporting a model</h2>To export a model you have already created or edited in Data Graphs, click Export Model in the Domain Model area, then choose the format you would like to export in. You can check a preview of the export before downloading to your hard drive. There is also an option to copy the contents of the model to your clipboard.

Managing data

About the API

The Data Graphs API is a REST API that allows you to interact with your data, letting you query, retrieve, filter, facet, and sort Concepts from your Datasets. You can also access individual Datasets and search within them, or federate across all your data.
	 The API provides the following core capabilities:<ul>
	
<li>Authentication</li>	
<li>Full text search</li>	
<li>Querying and filtering data</li>	
<li>Faceting</li>	
<li>Sorting and paging</li>	
<li>Creating Concepts</li></ul>
	 Although you can develop directly against the API, if you are coding in Javascript we recommend using the <a href="https://support.datagraphs.io/client-sdk/set-up/get-started">Data Graphs Javascript Client SDK</a>.<h2>Using the API</h2>
	 The API's Base URL is:
	 <code>https://api.datagraphs.io</code>
	 All requests require an&nbsp;API key&nbsp;and those to private Datasets must also include&nbsp;an&nbsp;OAuth 2.0 access token. For more information see <a href="https://support.datagraphs.io/knowledge-base/using-data-graphs-api/making-a-request">Making a Request</a>.<h2>Testing the API</h2>
	 If you have a&nbsp;Developer,&nbsp;Owner, or Administrator role on a given account, you can test each endpoint against your own data in the <a href="https://support.datagraphs.io/api-docs/overview">Support Portal API documentation</a>. Once logged in, just select the relevant application from the account menu in the nav bar.

Webhooks

Webhooks are an integration mechanism that allow you to trigger actions in a downstream business system or application in response to certain Data Graphs events, such as creating or updating a Concept. This lets you react to changes in Data Graphs without having to poll the API. They are essentially a push integration.Data Graphs webhooks to respond to the following event types:<ul><li>Concept Created</li><li>Concept Updated</li><li>Concept Merged</li><li>Concept Migrated</li><li>Concept Deleted</li><li>Candidate Concept Accepted</li><li>CSV Imported</li><li>Dataset Deleted</li><li>All Concepts in Dataset Deleted</li><li>All Concepts for Type Deleted</li><li>Multiple Concepts Deleted</li></ul>Each can listen for changes in all Datasets or can be constrained to a specific Dataset.When one of these events occurs, Data Graphs sends a POST request to your external environment with the event&#39;s details in the payload; examples of each type of payload are listed below. In fact, you can set up a webhook to make multiple POST requests by configuring multiple endpoints;<h2>Creating a webhook</h2>To create a webhook you must have the role Owner, Administrator or Developer. 1) Navigate to the <a href="https://app.datagraphs.io/_account/_project/_manage/project-webhooks">Webhooks</a> screen in project management:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/63073995c1ba4b3dfdae2f3c/file-CLJLXfX40K.png" style="width: 100%; max-width: 100%; " />2) Click on the Add Webhook button and select an Event Type and Target Dataset, and add the Endpoint of the webhook that will be invoked.In the following example, any Concept added to the Organizations Dataset will send details of that event to https://webhook-domain.com/endpoint:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/63073c4e86ac2a0f0724a3a8/file-CVJX7Iij1z.png" style="background-color: initial; width: 520px;">You can add additional endpoints to each event and pass authentication credentials or an API key to each endpoint. 3) When you have configured your hook, click Save and the hook will be ready.4) Clicking the Test button on your new hook will enable you to trigger it manually using a sample payload and check that it is received correctly at the endpoints(s) you have provided.<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/63073d5f549d66420b99a9ee/file-V6g4gXGy1T.png" style="width: 752px; max-width: 100%; " /><h2>Pre-Commit Endpoint</h2>If you choose to target All Datasets there is an additional option to create a single Pre-Commit endpoint for a create, update, merge, migrate or delete Concept event.<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/63073f9cc1ba4b3dfdae2f77/file-X34N1eqyK3.png" style="width: 544px; max-width: 100%; " /> This allows a consumer of the pre-commit hook to carry out an impact assessment on your data or the event before carrying out the action. It allows a downstream system to either cancel the change entirely, approve the change, or respond with an assessment or warning that the Data Graphs user can interpret.Pre-Commit webhooks will handle three cases:<ul><li>No impact – the action is completed with no notification in the UI.</li><li>Reject – a modal informs the user that the action cannot be completed.</li><li>Warning – a modal informs the user that the action can be completed with details of the impact with a prompt to continue.</li></ul><h2>Webhook request sample payloads</h2><h4>ConceptCreated</h4><pre style="margin-left: 20px;">{
 "type": "DataObjectEvent",
 "guid": "event-guid",
 "epoch": 1605781971,
 "targetDataset": {
 "name": "Concepts",
 "id": "urn:demo:concept"
 },
 "operation": "Created",
 "eventDate": "2020-11-19T10:32:33.518Z",
 "eventType": "DataObjectCreated",
 "eventTarget": "urn:demo:Concept:guid",
 "account": "demo",
 "sourceType": "User",
 "eventAgent": {
 "id": "urn:demo:user:guid",
 "name": "Demo User"
 },
 "objectVersion": {
 "label": "label1",
 "prop1": "value1",
 "prop2": "value2",
 "id": "urn:demo:Concept:guid",
 "type": "Concept"
 }
}
</pre><h4>ConceptUpdated</h4><pre style="margin-left: 20px;">{
 "type": "DataObjectEvent",
 "guid": "event-guid",
 "epoch": 1605781971,
 "targetDataset": {
 "name": "Concepts",
 "id": "urn:demo:concept"
 },
 "operation": "Modified",
 "eventDate": "2020-11-19T10:32:33.518Z",
 "eventType": "DataObjectUpdated",
 "eventTarget": "urn:demo:Concept:guid",
 "account": "demo",
 "sourceType": "User",
 "eventAgent": {
 "id": "urn:demo:user:guid",
 "name": "Demo User"
 },
 "objectVersion": {
 "label": "label1",
 "prop1": "value1",
 "prop2": "value2",
 "id": "urn:demo:Concept:guid",
 "type": "Concept"
 },
 "propertiesModified": [
 {
 "propertyName": "prop1",
 "newValue": "New value of prop1",
 "oldValue": "Old value of prop1"
 }
 ]
}
</pre><h4>ConceptDeleted</h4><pre style="margin-left: 20px;">{
 "type": "DataObjectEvent",
 "guid": "event-guid",
 "targetDataset": {
 "name": "Concepts",
 "id": "urn:demo:concept"
 },
 "operation": "Deleted",
 "eventDate": "2020-11-19T10:32:33.518Z",
 "eventType": "DataObjectDeleted",
 "eventTarget": "urn:demo:Concept:guid",
 "account": "demo",
 "sourceType": "User",
 "eventAgent": {
 "id": "urn:demo:user:guid",
 "name": "Demo User"
 },
 "objectVersion": {
 "label": "label1",
 "prop1": "value1",
 "prop2": "value2",
 "id": "urn:demo:Concept:guid",
 "type": "Concept"
 }
}
</pre><h4>ConceptMerged</h4><pre style="margin-left: 20px;">{
 "type": "DataObjectEvent",
 "guid": "event-guid",
 "epoch": 1605781971,
 "targetDataset": {
 "name": "Concepts",
 "id": "urn:demo:concept"
 },
 "operation": "Modified",
 "eventDate": "2020-11-19T10:32:33.518Z",
 "eventType": "DataObjectMerged",
 "eventTarget": "urn:demo:Concept:guid",
 "account": "demo",
 "sourceType": "User",
 "eventAgent": {
 "id": "urn:demo:user:guid",
 "name": "Demo User"
 },
 "objectVersion": {
 "label": "label1",
 "prop1": [
 "value1 updated",
 "value2 updated"
 ],
 "prop2": "value2",
 "id": "urn:demo:Concept:guid",
 "type": "Concept"
 },
 "propertiesModified": [
 {
 "propertyName": "prop1",
 "newValue": [
 "value1 updated",
 "value2 updated"
 ],
 "oldValue": [
 "old value of prop1",
 "old value of prop1"
 ]
 },
 {
 "propertyName": "prop1",
 "newValue": "2020-11-19T10:36:46.869Z",
 "oldValue": "2020-11-19T10:34:27.694Z"
 }
 ],
 "sourceIds": [
 "urn:demo:Concept:merged-concept-guid"
 ]
}
</pre><h4>CandidateAccepted</h4><pre style="margin-left: 20px;">{
 "type": "CandidateEvent",
 "guid": "event-guid",
 "epoch": 1605781971,
 "targetDataset": {
 "name": "Concepts",
 "id": "urn:demo:concept"
 },
 "operation": "Modified",
 "eventDate": "2020-11-19T10:32:33.518Z",
 "eventType": "CandidateAccepted",
 "eventTarget": "urn:demo:Concept:guid",
 "account": "demo",
 "sourceType": "User",
 "eventAgent": {
 "id": "urn:demo:user:guid",
 "name": "Demo User"
 },
 "objectVersion": {
 "label": "label1",
 "prop1": "value1",
 "prop2": "value2",
 "id": "urn:demo:Concept:guid",
 "type": "Concept"
 }
}
</pre><h4>CSVImported</h4><pre style="margin-left: 20px;">{
 "type": "CSVImport",
 "guid": "event-guid",
 "epoch": 1605781971,
 "targetDataset": {
 "name": "Concepts",
 "id": "urn:demo:concept"
 },
 "operation": "Created",
 "eventDate": "2020-11-19T10:32:33.518Z",
 "eventType": "CSVImported",
 "account": "demo",
 "sourceType": "User",
 "objectCount": 100,
 "eventAgent": {
 "id": "urn:demo:user:guid",
 "name": "Demo User"
 },
 "objectVersions": [
 {
 "label": "label1",
 "prop1": "value1",
 "prop2": "value2",
 "id": "urn:demo:Concept:guid",
 "type": "Concept"
 },
 {
 "label": "label1",
 "prop1": "value1",
 "prop2": "value2",
 "id": "urn:demo:Concept:guid2",
 "type": "Concept"
 },
 {
 "label": "label1",
 "prop1": "value1",
 "prop2": "value2",
 "id": "urn:demo:Concept:guid3",
 "type": "Concept"
 }
 ]
}
</pre>

Authentication

Access to the API is granted via an API key and, for private Datasets, an optional set of OAuth credentials. These are unique to each application and bound to the project in which they are created. <h2>Generating application credentials</h2>To create application credentials, navigate to the <a href="https://app.datagraphs.io/_account/_project/_manage/project-applications">Applications screen</a> of your current project. Note this is only accessible by users with one of the roles Owner, Administrator or Developer.Click Create New Application to create a new set of API credentials. You must name your application and choose whether it has read access or read/write access to your data:<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/630738dac1ba4b3dfdae2f33/file-fMMa9kHfpz.png" style="max-width: 100%; " /><h2>Generate an OAuth 2.0 token</h2>Once you have your application credentials, you can use them to generate the access token you&#39;ll need for calls to private Datasets. Use the <code class="inline-code">clientId</code> and <code class="inline-code">clientSecret</code> in the body of a request to <code class="inline-code">POST /oauth/token</code>  as follows:<pre>	{
 	 &quot;clientId&quot;: &quot;{clientId}&quot;, 
 	 &quot;clientSecret&quot;: &quot;{clientSecret}&quot;
	}
</pre>and don&#39;t forget to add a request header for the API Key, e.g. <code class="inline-code">x-api-key: abcdefg123456kjhgf7654</code> The response will be in the form:<pre>	{ 
 	 &quot;access_token&quot;: &quot;eyJhbGciOiJSUzI1N.....&quot;, 
 	 &quot;expires_in&quot;: 86400, &quot;token_type&quot;: &quot;Bearer&quot;
	}
</pre>

Query parameter reference

Datagraphs API makes a range of query parameters available for organizing and refining searches for Datasets and Concepts. <h4>Definitions</h4><table><tbody><tr><td><code class="inline-code">pageSize</code> </td><td> The number of results to return in the response, eg <code class="inline-code">pageSize=10</code> </td></tr><tr><td><code class="inline-code">pageNo</code> </td><td> The page number indicating which set of results should be returned in the response, eg <code class="inline-code">pageNo=2</code> </td></tr><tr><td><code class="inline-code">sort</code> </td><td> Sorts the results in the response using a specified field and direction, eg <code class="inline-code">sort=property1:asc,property2:desc</code> </td></tr><tr><td><code class="inline-code">filter</code> </td><td> A expression that filters a request. It is a string that takes the form <code class="inline-code">{property}:{operator}{value}</code> or uses a special function</td></tr><tr><td><code class="inline-code">q</code> </td><td> Full text search, eg <code class="inline-code">q=name</code> </td></tr><tr><td><code class="inline-code">boost</code> </td><td>Full text search field boosts<code class="inline-code">boost=property:{boost}</code> where <code class="inline-code">property</code> is a text property of a class, and <code class="inline-code">boost</code> is a score multiplication factor, using the same syntax factor as used in OpenSearch</td></tr><tr><td><code class="inline-code">facets</code> </td><td>Facets to be listed, eg, <code class="inline-code">facets=type</code> </td></tr><tr><td><code class="inline-code">facetSize</code> </td><td> Number of facets to include in results, eg<code class="inline-code">facetSize=10</code> </td></tr><tr><td><code class="inline-code">dateFacets</code> </td><td> Date facets, eg <code class="inline-code">dateFacets=publishedDate:1d:1w:1M</code> </td></tr><tr><td><code class="inline-code">fields</code> </td><td> List of fields to be included in the response, eg<code class="inline-code">fields=id,label,image</code> </td></tr><tr><td><code class="inline-code">embed</code> </td><td>List of ids of related properties to be embedded in the response, eg <code class="inline-code">embed=id1,id2,id3</code> or for all properties <code class="inline-code">embed=_all</code> Embed multiple levels using the syntax <code class="inline-code">embed=level:{level}</code> where <code class="inline-code">level</code> = 1, 2 or 3 <code class="inline-code">embed=level:1</code> is equalivalent to <code class="inline-code">embed=_all</code> </td></tr><tr><td><code class="inline-code">ids</code> </td><td>List of Concept ids to be returned (separated by a comma), eg <code class="inline-code">ids=id1,id2,id3</code> </td></tr><tr><td><code class="inline-code">includeDateFields</code> </td><td>A boolean flag that will include the automatic date fields (<code class="inline-code">_createdDate</code> and <code class="inline-code">_lastModifiedDate</code> in the Concept JSON response, e.g. <code class="inline-code">includeDateFields=true</code>this flag defaults to <code class="inline-code">false</code> </td></tr></tbody></table><h4>Building a filter expression</h4>Filter expressions can be constructed from a property, value and optional operator. More complex queries can use a filter function (see below).In its simplest form a filter expression consists of a property and a value, eg <code class="inline-code">filter=property1:value1</code> , where the separator (:) is equivalent to &quot;=&quot;. Adding an operator allows for different types of comparisons. Filter expressions can be combined using <code class="inline-code">,</code>  (AND) or <code class="inline-code">|</code>  (OR). Using parentheses around combinations of expressions – eg <code class="inline-code">({expression1},{expression2})</code>  – overrides operator precedence.The following defines the rules for each element in a constructed filter expression:<table><tbody><tr><td>Property</td><td> A path representing the field to filter on.</td><td><ul><li>It matches <code class="inline-code">[a-zA-Z_][a-zA-Z0-9_.]</code> .</li><li>It supports <code class="inline-code">.</code>  separated paths.</li><li>It can contain only alpha-numeric characters and <code class="inline-code">_</code> .</li><li>It cannot contain whitespace.</li><li>It must start with a letter.</li></ul></td></tr><tr><td>Operator</td><td> Used to compare values (on its own is roughly =); optional.</td><td><ul><li><code class="inline-code">-</code>  not</li><li><code class="inline-code">&gt;</code>  greater than</li><li><code class="inline-code">&gt;=</code>  greater than or equals</li><li><code class="inline-code">&lt;</code>  less than</li><li><code class="inline-code">&lt;=</code>  less than or equals</li><li><code class="inline-code">[</code>  value, value, ... <code class="inline-code">]</code>  in group</li></ul></td></tr><tr><td>Value</td><td>A string containing the value to match the expression against.</td><td><ul><li>It can contain whitespace.</li><li>Dates and datetimes should be in ISO 8601 format.</li></ul></td></tr></tbody></table><h3> Filter functions</h3>Functions for more complex queries follow the format <code class="inline-code">filter=_functionName(arg1, arg2, etc)</code> . The following are supported:<h4>_has()</h4>Search for Concepts where a given property is populated.<h4>_lacks()</h4>Search for Concepts where a given property is undefined.Where a property is nested, <code class="inline-code">_has()</code> and <code class="inline-code">_lacks()</code> can accept the path to that property, eg <code class="inline-code">_has(address.postcode)</code> , but will not filter on an object, eg <code class="inline-code">_has(address)</code> . <h3>Geospatial Functions</h3><h4>_within()</h4>Search for Concepts within a given area. Coordinates can be provided either as latitude and longitude in the format <code class="inline-code">(lat, long)</code> , or as a geohash. If two coordinates are provided, they define the top left and bottom right corners of the search area as a bounding box. Three or more coordinates define the search as a polygon.NB This function can only be used with Concepts whose properties include either a latitude/longitude pair or a geohash property. <h4>_near()</h4>Search for Concepts within range of a given location. Coordinates can be provided either as latitude and longitude in the format <code class="inline-code">(lat, long)</code>  or as a geohash.The following units are supported for distance:<ul><li><code class="inline-code">mi</code>  – miles</li><li><code class="inline-code">km</code>  – kilometres</li><li><code class="inline-code">m</code>  – metres</li><li><code class="inline-code">cm</code>  – centimetres</li><li><code class="inline-code">mm</code>  – millimetres</li></ul>NB This function can only be used with Concepts whose properties include either a latitude/longitude pair or a geohash property. <h3>Filter examples</h3>The following expressions can all be used on a Search Concepts query:<h4>Comparisons</h4><ul><li>Search Concepts where <code class="inline-code">string1</code> equals <code class="inline-code">value1</code> <code class="inline-code">filter=string1:value1</code> </li><li>Search Concepts where <code class="inline-code">string1</code>  equals <code class="inline-code">value1</code>  and <code class="inline-code">string2</code>  equals <code class="inline-code">value2</code> <code class="inline-code">filter=string1:value1,string2:value2</code> </li><li>Search Concepts where <code class="inline-code">string1</code>  equals <code class="inline-code">value1</code>  and <code class="inline-code">string2</code>  does not equal <code class="inline-code">value2</code> <code class="inline-code">filter=string1:value1,string2:-value2</code> </li><li>Search Concepts where <code class="inline-code">string1</code>  equals <code class="inline-code">value1</code>  or <code class="inline-code">value2</code> <code class="inline-code">filter=string1:[value1,value2]</code> </li></ul> <h4>Dates</h4>All Concepts have two properties <code class="inline-code">_createdDate</code> and <code class="inline-code">_lastModifiedDate</code> that are internally and automatically maintained by the graph. They are prefixed with an underscore. <ul><li>Search Concepts created between <code class="inline-code">2020-01-01</code>  and <code class="inline-code">2020-02-01</code> <code class="inline-code">filter=_createdDate:&gt;=2020-01-01,_createdDate:2020-02-01</code> </li><li>Search Concepts created or modified since  <code class="inline-code">2020-01-01</code> <code class="inline-code">filter=_createdDate:&gt;=2020-01-01|_lastModifiedDate:&gt;=2020-01-01</code> </li><li>Search Concepts where <code class="inline-code">string1</code>  equals <code class="inline-code">value1</code>  and it was created or modified since <code class="inline-code">2020-01-01</code> <code class="inline-code">filter=string1:value1,(_createdDate:&gt;=2020-01-01|_lastModifiedDate:&gt;=2020-01-01)</code> </li><li>You can also filter using the above pattern using any <code class="inline-code">date</code> or <code class="inline-code">datetime</code> properties that you have modelled in your project using the date property name.</li></ul> <h4>Geospatial</h4><ul><li>Search Concepts within 100 miles of coordinates (-40, 70)<code class="inline-code">filter=_near((-40, 70), 100mi)</code> </li><li>Search Concepts within a polygon with points (-40, 70), (-30, 60), (-35, 60)<code class="inline-code">filter=_within((-40, 70) (-30, 60), (-35, 60))</code> </li><li>Search Concepts within a box with top left corner (-40, 70) and bottom right corner (-30, 60)<code class="inline-code">filter=_within((-40, 70) (-30, 60))</code> </li></ul> <h4>Property validation</h4><ul><li>Search Concepts where <code class="inline-code">property1</code> is populated<code class="inline-code">filter=_has(property1)</code> </li><li>Search Concepts where <code class="inline-code">property1</code> on <code class="inline-code">object1</code> is populated<code class="inline-code">filter=_has(object1.property1)</code> </li><li>Search Concepts where <code class="inline-code">property1</code> is undefined<code class="inline-code">filter=_lacks(property1)</code> </li><li>Search Concepts where <code class="inline-code">property1</code> on <code class="inline-code">object1</code> is undefined<code class="inline-code">filter=_lacks(object1.property1)</code> </li></ul>

Using Data Graphs API

Managing users

Data Graphs users can be added to an account, assigned roles and removed from an account. They can also be added to individual projects. Team members must have either the&nbsp;Owner&nbsp;or&nbsp;Administrator&nbsp;role to perform these tasks.<h2>Managing users at Account level</h2>
	 Click on the user icon in the top right of the app nav bar and select&nbsp;Manage Account from the dropdown menu and Users from the sidebar.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6307475f66967f4ba394b0aa/file-nOEIDTfpHT.png"><h2>Inviting a user</h2>
	 Click the&nbsp;Invite&nbsp;button and&nbsp;enter the user's email address. Then choose the role they will have in your Data Graphs account.&nbsp;Find out <a href="https://support.datagraphs.io/knowledge-base/managing-your-account/team-roles">here</a> the permissions associated with each role.
	 Selecting&nbsp;Owner&nbsp;or Administrator&nbsp;gives them that role across all projects:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/62e26bf9c35bbc3e190ae4f7/file-2Kx31Bvf1d.png" style="width: 617px;">
	 Other types of role are assigned to specific projects, and users can be assigned different roles on different projects:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/62e26ce3a3bd513965054136/file-hoLpDxH3iw.png" style="width: 616px;">
	 Invitations will expire after 48 hours but can be renewed by clicking Manage Invitation. You can also delete invitations you no longer need.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/630747f7c1ba4b3dfdae2fa1/file-uvOZI81amI.png" style="width: 615px;"><h2>Updating a user's role</h2>
	 Clicking&nbsp;Manage User&nbsp;allows you to update a user's role(s). It is also possible to remove users with Developer,&nbsp;Editor, Data Editor&nbsp;and Viewer&nbsp;roles.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6071d2a5e0324b5fdfd09a6d/file-WfFMA2dYBP.png" style="width: 667px;"><h2>Managing users for a project</h2>
	 You can also manage users with&nbsp;Developer,&nbsp;Editor,&nbsp;Data Editor&nbsp;and&nbsp;Viewer&nbsp;roles at the project level by selecting Manage Project&nbsp;from the user menu and then&nbsp;Users in the sidebar.<h2></h2>

Team roles

A Data Graphs user is assigned a team role. These roles are:<ul><li>Owner – the person who creates the Data Graphs account is assigned the Owner role, and has super-admin rights to manage the subscription, invite users, manage the account and can perform all available actions. Other users can also be assigned the Owner role, with all the same permissions, although they cannot modify the original owner&#39;s role.</li><li>Administrator – can manage the account, users and all available actions, but cannot manage or see the subscription and billing screens.</li><li>Developer – can read Datasets and events, write Datasets, export data, manage applications and web hooks to manage API integrations.</li><li>Editor – can read and write Datasets and Concepts and can export data</li><li>Data Editor – can read Datasets and write Concepts</li><li>Viewer – has read only access, can only navigate and view data</li></ul>You can change a user&#39;s role across all projects in the <a href="https://app.datagraphs.io/_account/_manage/account-users" target="_blank">account management Users screen</a> and, for a given project, in the <a href="https://app.datagraphs.io/_account/_project/_manage/project-users">project management Users screen</a>.

GET STARTED

MANAGING DATA

USING DATA GRAPHS API

MANAGING YOUR ACCOUNT

Making a request

Headers