Simple vocabularies

What is a Dataset?

About the API

Team roles

Managing users

Building a knowledge graph

Subclassing and inheritance

Concept types

Search facets

Creating a Dataset

Data types

What is a Concept?

Importing data

Viewing and modifying a Dataset schema

Identifiers

Authentication

Webhooks

Deleting Concepts

Searching a Dataset

Query parameter reference

Merging Concepts

Custom validation rules

How to link Concepts

Federated Search

Making a request

Data Graphs' information management is based around the Dataset. This is where you define your classes, or types, and the relationships between them, and where you import your data, or Concepts.
	 This simplest way to use a Dataset is to create one per type. This approach is suitable for data comprising lists or collections of things.&nbsp;For example, in a geographical domain including lists&nbsp;of countries, flags and governments, your Datasets would be Countries, Flags and Governments, with each defining the relevant type and its properties. In its simplest form, a vocabulary in a Dataset might be just a list of Key–Label pairs.
	 However, if you are working with more complex relationships, eg in well documented a knowledge graph, then you should consider carefully <a href="/knowledge-base/get-started/building-a-knowledge-graph">how you define your types among your Datasets</a>.
	 For more information see <a href="/knowledge-base/managing-data/what-is-a-dataset">What is a Dataset?</a> and <a href="/knowledge-base/managing-data/what-is-a-concept">What is a Concept?</a>.<h2>Building a simple dataset</h2>
	 You can do this in 4 simple steps:<h4>1. Create a Dataset</h4>
	 Click on Create New Dataset&nbsp;on the <a href="https://app.datagraphs.io/account" target="_blank">Data Graphs app homepage</a>.&nbsp;Give your Dataset a name and decide whether it should be public or private.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60718690f8c0ef2d98df10f0/file-aAshbuVw7b.png" style="width: 587px;"><h4>2. Add a&nbsp;Concept&nbsp;type&nbsp;</h4>
	 Create your own custom concept type or choose one of Data Graphs' pre-created templates.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60718ec34466ce6ddc5f3490/file-ptnhmI8YEs.png" style="width: 583px;"><h4>3.&nbsp;Define Custom Type properties</h4>
	 Every Data Graphs type has an id and a label as a minimum but you can add as many others as required by clicking the + symbol on the right hand side of the last property in the list.
	 Note: if your entities come with their own ids, you should select Manual Identifiers. Alternatively, Data Graphs will create Automatic Identifiers for you.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6113d6f0766e8844fc34f778/file-ATnTHv9KFp.png" style="width: 673px;"><h4> 4. Add your data&nbsp;</h4>
	 You can do this 3 ways:<ul>
	<li>Create a Concept manually from the&nbsp;Add New Concepts&nbsp;page in the Data Graphs app</li>	<li>Upload a CSV from the&nbsp;Import Data&nbsp;page for the Dataset</li>	<li>Load Concepts via the <a href="/api-docs">Data Graphs API</a> either individually or in bulk</li></ul>
	 For more information see <a href="/knowledge-base/managing-data/importing-data">Importing data</a>.
	 <a href="/api-docs#/paths/~1{your-account-key}~1{datasetId}/post" target="_blank"></a>

If your data has more complex relationships than simple lists or collections, it is useful to design a domain model as it will help your define your Datasets.<h2>Designing a domain model</h2>
	 You can create a domain model on paper or with a drawing tool such as LucidChart, Visio or OmniGraffle. It should define all your Concepts (types/classes) and the relationships between them (their properties).&nbsp;
	 In the following Food domain model, the blue ovals represent your Concept types and the arrows the relationships between them; their properties. The white rectangle signifies a primitive datatype. So a Recipe, for example, has a chef property of type Person, a forDish property (Dish) and a steps property (Text - a primitive datatype).
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6113d8c06ffe270af2a97d9c/file-CXxZylDdx8.png" style="width: 511px;">
	 For more information see <a href="/knowledge-base/managing-data/what-is-a-dataset">What is a Dataset?</a> and <a href="https://secure.helpscout.net/knowledge-base/managing-data/what-is-a-concept">What is a Concept?</a>.&nbsp;We have also created a video that walks you through this process <a href="https://datagraphs.com/demos/how-to-setup-your-data-sets" target="_blank">here</a>.<h2>Build your datasets</h2>
	 With a well defined domain model you are in a position to create your Concept types and their relationships. You can do this in one or more Datasets depending on how you prefer to organise and manage your data. While the Datasets themselves confer no semantic meaning on your domain model, they do allow you to collect concepts (entities) of similar types together which might make it easier for to manage them. Of course, you could build your entire knowledge graph in a single Dataset.&nbsp;<h4> 1. Create leaf concept types</h4>
	 Start by creating those types that have no links outward to other types (the leaf nodes). In the Food domain model above, these are Occasion, Ingredient, Cuisine and Person. Then create the concept types that have relationships to other types (that you have already created).<h4> 2. Creating relationships</h4>
	 Relationships are automatically created when you define a type that has another type as a property. In our example, Recipe has a chef property whose type is Person. This is why creating the Person type before the Recipe type makes sense. You can still come back and edit a type later to add a property if you did not create the dependant type first (the Person in this example).
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6113ddc3b37d837a3d0e2c9d/file-vAR7Y8ZcCR.png" style="width: 525px;"><h4> 3. Define non-relational properties (primitive or datatype properties)</h4>
	 These are properties with standard primitive datatypes (text, dates, keywords, booleans etc). You can find definitions of these primitives <a href="/knowledge-base/managing-data/data-types">here</a>. &nbsp;In this case, the steps property is of type Text.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6113de5864a230081ba1e357/file-tda0XHL3th.png" style="width: 508px;"><h4>4. Review the domain</h4>
	 Once you have created all your types and their properties, you can see a visualisation of the domain model in Data Graphs <a href="https://app.datagraphs.io/account/_domain-model">here in the app</a> and check to see if it aligns with your own domain model.<h4> 5. Import your data</h4>
	 You can import your data in 3 ways:<ul>
	
<li>Create Concepts manually from the&nbsp;Add New Concepts&nbsp;page using the Data Graphs UI</li>	
<li>Upload CSVs from the&nbsp;Import Data&nbsp;page in a Dataset</li>	
<li>Create Concepts via the <a href="/api-docs">Data Graphs API</a> - either individually or in bulk.</li></ul>
	 For more information see <a href="/knowledge-base/managing-data/importing-data">Importing data</a>.

Get started

A Dataset is a namespace or bucket for collecting or grouping concepts together.
	 The cards listed on your Data Graphs app home page each represent one Dataset. On this card you can see how many Concepts are contained in this Dataset and the types of Concepts it 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;">
	 Data Sets provide two main functions:<ol>
	
<li>Information management - a way to efficiently or conveniently manage data</li>	
<li>Security - a way to make some of your data public or privately accessible to applications at integration time</li></ol><h2></h2><h2></h2><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&nbsp;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 data sets 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. &nbsp;This defines how the data within the Dataset is accessed by the Data Graphs API.&nbsp;
	 Private - A Dataset declared as private can only be accessed using OpenID credentials. This means your data in this Data Set is secure and can only be accessed via an authenticated user request. &nbsp;Machine-2-Machine OpenID / oAuth credentials can be setup in the account management configuration settings.
	 Public - A Dataset declared as public can be accessed using just your API key. These data requests can be made without authentication.

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 as well as benefiting from the ability to facet on both the child and parent class.
	<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 you could see any type of vehicle plane of motor vehicle.
	 
	
	 
	<h2> Planning your Concept type hierarchy</h2>
	 If you have already designed your model it is advised to define your Concept types in Data Graphs starting from the top down. Start with the parent type and work down to define more specific&nbsp;Concept&nbsp;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&nbsp;Concept&nbsp;types.<h2>Creating subclasses</h2>
	 You create a subclass or a sub-type when creating a&nbsp;Concept&nbsp;type schema in a Dataset. After naming your&nbsp;Concept, you have the option of choosing a 
	Parent Type for the&nbsp;Concept&nbsp;you are defining.
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608675bef8c0ef2d98df609a/file-AL51K2sLxl.png">
	 By selecting the 
	Include {type} properties option, your new subclass will inherit (re-use) the properties from the parent type. This is most likely what you will need to.<h2>Managing types</h2>
	 The 
	<a href="https://app.datagraphs.io/account/_manage-types">Manage Types</a> screen allows you to see a visual representation of your current type hierarchy. This view is accessible from the main account menu in the navbar called Manage Types. Within this screen you can remove a type that you no longer require or 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&nbsp;Concept&nbsp;property defines a relationship to another&nbsp;Concept&nbsp;type/class the UI allows you to select&nbsp;Concept&nbsp;instances of that type and all its subclasses. For example, if you create a class Football Team that is a sub-class of Organization, and you then create a property on a&nbsp;Concept&nbsp;that references an Organization, as Football Team is a sub-class of Organization, football teams can also be assigned to that property. Search facets and&nbsp;API queries also obey the usual semantics of transitive inference across a class hierarchy.
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608678378af76a714bfdad60/file-x7YinLI0un.png">

Every&nbsp;Concept&nbsp;in your Data Graphs account is assigned a type or class by you. The type describes the semantics of the class of&nbsp;Concept&nbsp;(such as Person, Animal, Organisation, Football Team etc).&nbsp;
	 <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;type confers characteristics upon your data. It also enables you to query, navigate and facet data by type. For example in the federated search screen, there is a type facet presented by default as shown in the screenshot.
	 This type facet shows you how many&nbsp;Concepts&nbsp;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&nbsp;Concepts of that type, regardless of which Dataset the&nbsp;Concepts might be present in.<h2></h2><h2>Concept relationships</h2>
	 Concept types are used when creating a property that references or links to another&nbsp;Concept&nbsp;in your domain model. If you specify a specific type in this relationship, Data Graphs understand the range semantics of the relationship and is able to validate and constrain the Concept editor to only allow&nbsp;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;"><h2>Managing Concept types</h2>
	 While you can view and manage&nbsp;Concept&nbsp;types within each Dataset schema, there is a dedicated screen for viewing and managing all&nbsp;Concept&nbsp;types accessible from the main account menu in the navbar called Manage Types. This screen lists al the types across all your Datasets, and also lets you view the class hierarchy you have created through subclassing.
	 If you want to delete a specific&nbsp;Concept&nbsp;type that is not used you can do it from right hand side bar :
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60745b618996210f18bd25f6/file-Dk9XGAnvLR.png">

In addition to free text search Data Graphs provides search (filter) by facets. Facets are 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 concepts 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 it filters the currently returned set of&nbsp;Concepts to only those that match that facet and any 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.
	 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="/knowledge-base/managing-data/subclassing-and-inheritance">Subclassing and inheritance</a>.

To create a Dataset click on the create tile on the Data Graphs app homepage. You will be guided through a set of steps in which you define the types of Concepts you want your Dataset to contain.<h2>Step 1: Dataset settings</h2>
	 Choose an appropriate name for the Dataset, an example would be to name it after the collection of&nbsp;Concepts&nbsp;that it will contain. You need to name it unambiguously. The namespace for the&nbsp;Dataset&nbsp;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.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60718690f8c0ef2d98df10f0/file-aAshbuVw7b.png">
	 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 using oAuth / OpenID authentication.&nbsp;
	 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: Add a Concept type</h2>
	 Next you must add one or more types of&nbsp;Concepts&nbsp;that you want to include in the&nbsp;Dataset. We call this the Dataset Schema, You are able to add more Concept types later to an existing Dataset schema.
	 Choose the first type you want to add, either selecting an existing type you have already defined or one of the types we have defined for you, or create a brand new type. In the example below we are naming a new type Country as we want to include Country&nbsp;Concepts&nbsp;in the Dataset. When happy, click the Add Type button.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60718ec34466ce6ddc5f3490/file-ptnhmI8YEs.png"><h2>Step 3: Customise the type</h2><h3>Subclassing</h3>
	 Now you need to choose if this&nbsp;Concept&nbsp;type is sub-class of some existing type or not. If this Concept type is a sub-class, you can select the Parent Type from the drop-down list of existing types. If you do choose a parent type, you can then choose to include the properties from the parent&nbsp;Concept&nbsp;type in this new (child) type&nbsp;–&nbsp;typically you should choose to inherit the parent&nbsp;Concept&nbsp;properties.<h3>Automatic or manual identifiers</h3>
	 You must choose whether to use manual or automatic identifiers. If you choose manual, for every&nbsp;Concept&nbsp;of this type you create you will need to supply a unique identifier of your choosing. The identifier must be unique with respect to the class / type of Concept. If you choose automatic you will&nbsp;not need to supply identifiers for each&nbsp;Concept, instead Data Graphs will generate a globally unique identifier for you.<h3>Defining the Concept properties</h3>
	 Now add the properties to your Concepts schema. By default each&nbsp;Concept&nbsp;has an id and a label. The id property name cannot be changed by you can change the label property name to something else (e.g. name&nbsp;is a good alternative).
	 Now you can define the custom properties that will describe each instance of your Concept. In our Country example a Country may have a longName, a latitude and longitude, a capital city and a flagImage.
	 For each property you must choose its data type. Property data types can be primitive types like text, decimal, integer, boolean, or specialised data types like latitude / longitude, or you can choose to make a relationship property that will reference a different Concept type that may exist in this or any other&nbsp;Dataset.
	 For each property, you can choose modifiers, whether the property :<ul>
	
<li>is optional – you do not need to supply a value for an optional field when editing data</li>	
<li>is identifier&nbsp;–&nbsp;if you have selected manual identifiers, you may select one custom property as the field that will uniquely identify Concepts of this type. You do not need to choose a field to be the identifier, and instead you can just use the default id field if this is preferable. If you do define an identifier property, the property datatype must be a keyword or an integer.</li>	
<li>allow multiple – indicates if the property allows multiple values (an array).</li>	
<li>preview image – if you have selected an imageURL datatype, you can choose if this property holds a canonical preview image of the Concept.</li>	
<li>is nested –&nbsp;if you have defined a relationship property that references another Concept - you can optionally choose this to be nested inside the Concept itself. This allows you to create complex data structures within the concept. A more typical scenario is simply to link to Concepts elsewhere in your Datasets (the knowledge graph and linked-data pattern). In this case leave this option unchecked.</li></ul>
	 In our Country example I have chosen manual identifiers, which means I need to either use the standard&nbsp; id property, or I can define a new property that will uniquely identify every&nbsp;Concept. In this case we have defined an isoCode field and marked it as the identifier. &nbsp;You can see the other custom properties we have chosen for our Country type below :
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/607198a68af76a714bfd5e50/file-ocgLyD0nLs.png">
	 When you are happy with this Concept schema definition, click Review Types.&nbsp;<h2>Step 4: Review types and save the Dataset</h2>
	 Finally you get to review the&nbsp;Concept&nbsp;types you have defined for this Dataset, you can edit, remove, or add more types from this final screen. If &nbsp;you choose to add another type, you will repeat Step 2 and 3 for the additional&nbsp;Concept&nbsp;type.
	 When you are happy you have defined all the types you need, click the Save Dataset button and Data Graphs will create the Dataset empty , and ready for you to add Concepts into.

When you create a Dataset and define a new Concept you define the properties for the&nbsp;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&nbsp;– 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&nbsp;– decimal integers only, no whitespace, e.g. &nbsp;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, &nbsp;e.g. &nbsp;2021-04-17</li> 
 
<li>dateTime – an ISO-8601 dateTime, YYYY-MM-DDThh:mm:ssZ &nbsp;e.g. 2021-04-17T13:14:32Z , a timezone component can &nbsp;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&nbsp;– 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>URL – interpreted and validated as a URL</li> 
 
<li>imageURL –&nbsp;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></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.&nbsp; When you select a specific&nbsp;Concept&nbsp;type as the data type of some property, Data Graphs is able to validate and constrain the allowed&nbsp;Concept&nbsp;value to be only of this type.&nbsp; If you have utilised sub-classing, and the property range is some parent class&nbsp;Concept&nbsp;type, then Data Graphs will constrain the range of the relationship to include all&nbsp;Concepts of the parent class selected and the set of all sub-classes of this&nbsp;Concept&nbsp;type.

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 get to&nbsp;<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 must define whether the ids (the identifiers) of&nbsp;Concepts&nbsp;are manually supplied by you or automatically generated by Data Graphs.&nbsp;
	 Other properties of a&nbsp;Concept&nbsp;are entirely defined by you.
	 There are several ways of ingesting and maintaining&nbsp;Concepts&nbsp;in Data Graphs :<ul>
	
<li>You can import Concepts in bulk into a Dataset using either the CSV import wizard&nbsp;</li>	
<li>You can import Concepts via the Data Graphs API.</li>	
<li>You can manually create and update Concepts using the Data Graphs user interface</li></ul>

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 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 right 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 to have automatic identifiers you do not need an identifier column in the CSV file. If the Concepts are configured for manual identifiers you will need one of the columns in the CSV to hold the identifiers for the Concepts being ingested.</li>	
<li>You can match columns to relationship properties if the column contains identifiers of Concepts 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></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 identifier's are the 2-character ISO codes.<h3>Step 1: Prepare the CSV and schema, and upload the file</h3>
	 Our CSV is structured like this:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/608eb124f8c0ef2d98df874f/file-tNCQli5DQ3.png">
	 and we have created a Countries&nbsp;Dataset&nbsp;with a&nbsp;Concept&nbsp;type Country with these properties:
	 <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">

Once you have created a Dataset you may need to modify its schema, either to add new&nbsp;Concept&nbsp;types to it, or to modify the properties of a&nbsp;Concept&nbsp;within.
	 To view the schema of a&nbsp;Dataset&nbsp;and its&nbsp;Concepts&nbsp;you can click on the menu icon in the top right of a&nbsp;Dataset&nbsp;tile on the Data Graphs app homepage, and selecting the 
	Manage link.
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/607427b34466ce6ddc5f38cf/file-13fMnlmRGa.png" style="width: 631px;">
	This will take you to a screen showing a read-only view of the&nbsp;Dataset&nbsp;schema, its&nbsp;Concepts and their property definitions:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60742573e0324b5fdfd09eaa/file-DgTbuHkiYO.png" style="width: 692px;"><h2>Editing Concept properties</h2>
	To edit the properties of one of the&nbsp;Concept&nbsp;in the&nbsp;Dataset&nbsp;click the 
	Edit Schema button in the bottom corner of the&nbsp;Concept&nbsp;details pane. Note, you will not be able to modify the property of a&nbsp;Concept&nbsp;schema if&nbsp;Concept&nbsp;instances already exist for the type you are editing. You can always add more properties to a Concept definition by clicking the + icon to the right of the last property:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/607432b38996210f18bd24bb/file-557ZuRpJqc.png" style="width: 689px;"><h2>Adding a new Concept type to a Dataset</h2>
	To add a new Concept class/type to a&nbsp;Dataset&nbsp;schema, select a new Concept type from the 
	Add a new type drop list at the top right of the Edit Schema screen. Choose a predefined&nbsp;Concept&nbsp;type, or choose Custom to create one of your own:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60743407f8c0ef2d98df1562/file-SVw4OrK76X.png" style="width: 695px;">
	You will then be presented with a form to edit the properties of your new&nbsp;Concept.

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 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>For a given type, identifiers can be configured to be manual&nbsp;(provided by you, the user) or automatic&nbsp;(generated by Data Graphs).</li>	
<li>When you create a Concept schema in a Dataset you choose whether the IDs are manual or automatic.</li>	
<li>For manually provided identifiers, you can choose to use the generic "id" property (that is present for all Concepts) or use a custom property of the Concept that you choose to be the identifier.</li></ul><h2>URNs</h2>
	 Internally Data Graphs uses URNs to namespace identifiers by&nbsp;Concept&nbsp;type. A URN is like a URI but is not web resolvable. The URN pattern used in Data Graphs is <code>urn:{account}:{type}:{id}</code> for example <code>urn:test:Person:1a2b3c4d</code>. You will see these URNs when viewing&nbsp;Concept&nbsp;data.&nbsp;
	 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 identifiers</h2>If you choose manual identifiers when configuring a&nbsp;Concept&nbsp;type,&nbsp;you will need to provide a unique ID for every&nbsp;Concept&nbsp;of that type you create, either within the user interface or when using the API.
	 Why might you choose manual IDs? &nbsp;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, eg, 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">

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;">

You can search across data in a number of ways in Datagraphs. Either within a specific dataset or across all of the datasets in a given account.
	 If you want to search across all data you can use the search box on the home screen (this is also called "Federated Search"). You do not have to specify a search term you can perform an empty query that will return you 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;">
	 Alternatively you can restrict a search to a specific dataset. You do this by selecting a specific dataset from the home screen. The search will then be scoped to that dataset alone and its associated facets. You can return to search scoped to all the datasets at any time by returning 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="/knowledge-base/managing-data/search-facets">searching by facets</a> for more information.

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. Note that the id of the target concept will be retained, and send up 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.

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>

Linking data through semantic relationships is a critical part of building a useful knowledge graph. To do this there are a number of important concepts to understand:<ol>
	
<li>How graphs join data entities using linked-data principles</li>	
<li>Creating relationships in your domain or ontology model</li>	
<li>How to load related Concepts into that model using the Data Graphs app</li>	
<li>How to load in related concepts in bulk using CSV files</li>	
<li>How to load in related concepts in bulk using the API</li></ol><h2>Linked Data Principles</h2>
	 Linked-data patterns use the identity (the ID), of entities to connect them, this 
	id usually takes the form of a URI or a URN. In Data Graphs entities (Concepts) use URNs as identifiers. The URNs for a concept are globally unique in your knowledge graph and take the form:
<pre>urn:{account}:{type}:{id}
</pre>
	 For example :
<pre>urn:demo:Person:12345
</pre><h2></h2>
	 Thus two concepts, a Person and an Organization, are linked together via their IDs like this.
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/618e59abefc78d0553e59a61/file-jeYdFkmBy7.png" style="width: 701px;"><h2>Creating Relationships in the Domain Model</h2>
	 Creating relationships in your Data Graphs domain model is easy. It just requires some sequencing.&nbsp;
	 Given a relationship is made between the classes or types of concepts, for example a Person&nbsp; 
	<code>worksFor</code> an Organization, in this case, the Person type owns the relationship, so the relationship is defined by adding the property <code>worksFor</code> to the Person concept type/class. The datatype (or range) of the property must be set to <code>Organization</code>. This implies you need to create the Organization concept type/class before creating this property on the Person type.
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/618e89549ccf62287e5f5f29/file-rFV1oN9PGH.png">
	Once you have added your property, Data Graphs knows that this property belongs to a Person and can only have Organization concepts (or concepts that are sub-classes of Organization) assigned to this relationship.&nbsp;<h2>Loading linked data via the Data Graphs UI</h2>
	This is super-easy. Once the model is relationship aware (above), the UI understands the model, and when you edit a Concept (eg in this case a Person), when adding the worksFor property Data Graphs will only allow you select Organizations. If you have not already loaded any Organization instances, of course you will not be able to add one to your property.
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/618eaa992b380503dfe047b8/file-MYeTg868LW.png">
	Saving this will then create a Person (Jane Doe), connected to an Organization (Apple) by the worksFor property :
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/618eab6e64e42a671b636857/file-qE7pOlanbd.png"><h2>Loading linked data via CSV</h2>
	Loading data in bulk using the 
	<a href="https://support.datagraphs.io/knowledge-base/managing-data/importing-data">CSV importer</a> also uses the concept identifiers to make the relationship joins. Using our Person worksFor Organization example model, assuming we have created 3 organization concepts as follows :
<table>
<thead>
<tr>
	<td>
		Organization name
	</td>
	<td>
		Organization ID
	</td>
</tr>
</thead>
<tbody>
<tr>
	<td>
		Apple
	</td>
	<td>
		59k0AZ8rcripmaLcL2BisK
		 
	</td>
</tr>
<tr>
	<td>
		Amazon
	</td>
	<td>
		5ir3poyfNQLjjsra50BDRI
	</td>
</tr>
<tr>
	<td>
		Microsoft
	</td>
	<td>
		5qnrcsngabk85QSrrT4M1E
	</td>
</tr>
</tbody>
</table>
	If we then create a CSV of people that work for these organizations, with 2 columns person name and the identifier of the company they work for, like this:
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/618ec4e964e42a671b636904/file-bFx9TF55ov.png">
	If we load this CSV into our dataset using the CSV Importer, choosing to load these as Person concepts, and mapping the worksFor column to the worksFor property of the Person type, when we import, Data Graphs will automatically make the relationships between the Person and the Organization.&nbsp; You can see on line 5, Carol James works for two organizations so the worksFor column has the identifiers of both companies in a quoted array. The CSV importer lets us map our columns to our Person properties like this :
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/618ec5489ccf62287e5f60ba/file-Kvr6QzYx3v.png">
	and Data Graphs knows that the identifiers in the worksFor column must be Organizations from our domain model. It can just make the connections automatically during import. One the import completes, the graph of our people looks like this :
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/618ec5a82b380503dfe0486a/file-foE48clVK3.png"><h2>Loading linked concepts using the API</h2>
	When loading concepts using the Data Graphs API you need to POST the concepts to the dataset you want to insert them into. More information about the API POST request to create concepts can be 
	<a href="https://support.datagraphs.io/api-docs/[docs]#create-concept-s">found here</a>. When using the API you must send fully formed JSON in the request body, and for relationship properties you must identified the concept being connected by its fully qualified URN.
	For example to send Person concepts using our worksFor examples the JSON would like this (assuming the Person concept is defined using automatically assigned identifiers:
<pre>[
 {
 "type": "Person",
 "name": "Jane Doe",
 "worksFor": [
 "urn:test:Organization:5ir3poyfNQLjjsra50BDRI"
 ]
 },
 {
 "type": "Person",
 "name": "Jim Smith",
 "worksFor": [
 "urn:test:Organization:59k0AZ8rcripmaLcL2BisK"
 ]
 },
 {
 "type": "Person",
 "name": "John Jones",
 "worksFor": [
 "urn:test:Organization:59k0AZ8rcripmaLcL2BisK"
 ]
 },
 {
 "type": "Person",
 "name": "Carol James",
 "worksFor": [
 "urn:test:Organization:5qnrcsngabk85QSrrT4M1E",
 "urn:test:Organization:5ir3poyfNQLjjsra50BDRI"
 ]
 }
]
</pre>

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 home page that lists by typing into the search bar at the top of the page, and this will let you select a concept or if you hit return it will invoke a detailed full text search.&nbsp;
	&nbsp;Alternatively by clicking the arrow button highlighted below :
	<img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/61a0a1d8efc78d0553e5de20/file-xn1WxkuzCr.png">
	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">

Managing data

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="/client-sdk/set-up/get-started">Data Graphs Javascript Client SDK</a>.<h2>Testing the API</h2>
	 If you have an Owner or Administrator role on a given account, you can test each endpoint against your own data in the <a href="https://secure.helpscout.net/api-docs/overview">Support Portal API Docs</a>. Once logged in, just select the relevant application from the account menu in the nav bar.

Access to the API is granted via an API key and, for private&nbsp;Datasets,&nbsp;an optional set of OAuth credentials. These are unique to each application and bound to the account that created them.&nbsp;<h2>Generating application credentials</h2>
	 To create application credentials, navigate to the <a href="https://app.datagraphs.io/account/_manage/account-applications">Applications screen</a> of the Data Graphs app. Note this is only accessible by users with one of the roles&nbsp;Owner,&nbsp;Administrator&nbsp;or&nbsp;Developer.
	 Click Create New Application&nbsp;to create a new set of API credentials. You must name your application and choose whether it has&nbsp;read&nbsp;access or&nbsp;read/write&nbsp;access to your data.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6086710df8c0ef2d98df6067/file-eTsTJgpIIT.jpg"><h2>Generate an OAuth 2.0 token</h2>
	 Once you have your application credentials, you can use them to generate the access token you'll need for calls to private Datasets. 
	 
	 Use the <code>clientId</code> and <code>clientSecret</code> in the body of a request to <code>POST /oauth/token</code>&nbsp;as follows:
<pre>	{
 	 "clientId": "{clientId}", 
 	 "clientSecret": "{clientSecret}"
	}
</pre>
	 The response will be in the form:
<pre>	{ 
 	 "access_token": "eyJhbGciOiJSUzI1N.....", 
 	 "expires_in": 86400, "token_type": "Bearer"
	}
</pre>

Webhooks are an integration mechanism that allow you to trigger actions in a downstream business system or application in response to certain Data Graphs&nbsp;events, such as creating or updating a&nbsp;Concept.&nbsp;This lets you react to changes in Data Graphs without having to poll the API. They are essentially a&nbsp;push&nbsp;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 Deleted</li>	
<li>Candidate Concept Accepted</li>	
<li>CSV Imported</li></ul>
	 Each can listen for changes in all Datasets and all Concept types or can be constrained to a specific Dataset and/or Concept type.
	 When one of these&nbsp;events occurs, Data Graphs sends a POST request to your external environment with the event's details in the payload; examples of each type of payload are listed below.<h2>Creating a webhook</h2>
	 To create a webhook you must have the role Owner, Administrator&nbsp;or Developer.&nbsp;
	 1) Navigate to the <a href="https://app.datagraphs.io/account/_manage/account-webhooks">Webhooks</a> screen in account management:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60868f008af76a714bfdade7/file-RwiQxR9Opp.png">
	 2) Click on the Create New Webhook button and select event options you need to trigger your hook:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/60868f358996210f18bd6f7b/file-fghWDIVDMo.png" style="width: 427px; margin: 0px 10px 10px 0px;" alt="">
	 3) Choose the event type and optionally constrain it to a Concept type and/or a Dataset.
	 4) Add the URL of the endpoint the webhook will request when the event is fired.
	 If you need to pass authentication credentials an API key or some other value to your endpoint, you can add this via the request header options.
	 5) When you have configured your hook, click Create and the hook will be ready.
	 6) Clicking the&nbsp;Test button on your new hook will enable you manually trigger it using a sample payload and check that it is received correctly at the URL you have provided.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/617133b22b380503dfdfcacf/file-fI5qJA6l0G.png" style="width: 543px;">&nbsp;<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>

<h3></h3>
<table>
<tbody>
<tr>
	<td>
		<code>sort</code>
	</td>
	<td>
		Sorts the results in the response by a specified field and direction.
		 
		For example,&nbsp;
		<code>sort=property1:asc,property2:desc</code>
	</td>
</tr>
<tr>
	<td>
		<code>pageNo</code>
	</td>
	<td>
		The page number indicating which set of results should be returned in the response.
		 
		For example,&nbsp;
		<code>pageNo=2</code>
	</td>
</tr>
<tr>
	<td>
		<code>pageSize</code>
	</td>
	<td>
		The number of results to return in the response.
		 
		For example,&nbsp;
		<code>pageSize=10</code>
	</td>
</tr>
<tr>
	<td>
		<code>q</code>
	</td>
	<td>
		Full text search.
		 
		For example,&nbsp;
		<code>q=name</code>
	</td>
</tr>
<tr>
	<td>
		<code>facets</code>
	</td>
	<td>
		Facets to be listed.
		 
		For example,&nbsp;
		<code>facets=type</code>
	</td>
</tr>
<tr>
	<td>
		<code>dateFacets</code>
	</td>
	<td>
		Date Facets
		 
		For example,&nbsp;
		<code>dateFacets=publishedDate:1d:1w:1M</code>
	</td>
</tr>
<tr>
	<td>
		<code>embed</code>
	</td>
	<td>
		Embed
		 
		For example, embed=_all
	</td>
</tr>
<tr>
	<td>
		<code>ids</code>
	</td>
	<td>
		List of Concept&nbsp;ids to be returned (separated by comma).
		 
		For example,&nbsp;&nbsp;<code>ids=id1,id2,id3</code>
	</td>
</tr>
<tr>
	<td>
		<code>filter</code>
	</td>
	<td>
		Filters for the request.
		 
		For example,&nbsp;
		<code>filter=property1:value1,property2:value2</code> 
		 
		A filter expression&nbsp;is a string that provides the property, operator and value in the form&nbsp;<code>property:operatorvalue</code>
		<ul>
			<li>property – a path representing the field to filter on</li>
			<li>: – separator between property and an operator-value expression</li>
			<li>operator (optional) – how to compare values(on its own is roughly =)</li>
			<li>value – the value to match against</li>
		</ul>
		Property
		 
		Matches:&nbsp;
		<code>[a-zA-Z_][a-zA-Z0-9_.]</code>
		<ul>
			<li>can contain only alpha-numeric characters and&nbsp;<code>_</code></li>
			<li>cannot contain whitespace</li>
			<li>must start with a letter</li>
			<li>supports&nbsp;<code>.</code>&nbsp;separated paths</li>
		</ul>
		 
		Operator
		<ul>
			<li><code>-</code>&nbsp;not</li>
			<li><code>&gt;</code>&nbsp;greater than</li>
			<li><code>&gt;=</code>&nbsp;greater than or equals</li>
			<li><code>&lt;</code>less than</li>
			<li><code>&lt;=</code>&nbsp;less than or equals</li>
			<li><code>[</code>&nbsp;value, value, ...&nbsp;<code>]</code>&nbsp;in group</li>
		</ul>
		 
		Value
		 
		Any string containing the value to match against
		<ul>
			<li>can contain whitespace</li>
			<li>dates and datetimes should be in ISO 8601 format</li>
		</ul>
		 
		Functions Special filtering functions for more complex queries. These follow the format&nbsp;
		<code>filter=_functionName(arg1, arg2, etc)</code>. The following functions are supported:<ul>
			<li><code>near</code>&nbsp;- Find Concepts within range of a given location. The coordinates can be given either as latitute and longitude in the format&nbsp;
			<code>(lat, long)</code>&nbsp;or as a geohash. The following units are supported for distance:<ul>
				<li><code>mi</code>&nbsp;– miles</li>
				<li><code>km</code>&nbsp;– kilometres</li>
				<li><code>m</code>&nbsp;– metres</li>
				<li><code>cm</code>&nbsp;– centimetres</li>
				<li><code>mm</code>&nbsp;– millimetres</li>
			</ul>
			 This function requires Concepts to have either a latitude/longitude pair or a geohash property
			</li>
			<li><code>within</code>&nbsp;- Find Concepts within a given area. The coordinates can be given either as latitute and longitude in the format&nbsp;&nbsp;<code>(lat, long)</code>&nbsp;or as a geohash.&nbsp; If only 2 coordinates are given then the search will be done within a bounding box using those 2 coordinates at the top left and bottom right corners. If 3 or more coordinates are given then the search will be done within a polygon with points at those coordinates. This function requires Concepts to have either a latitude/longitude pair or a geohash property.</li>
		</ul>
		Combinations
		<ul>
			<li><code>,</code>&nbsp;– represents AND</li>
			<li><code>|</code>&nbsp;– represents OR</li>
			<li><code>(</code>&nbsp;filter expression&nbsp;<code>)</code>&nbsp;– overrides operator precedence</li>
		</ul>
		 
		Examples
		<ul>
			<li>Get all Concepts where&nbsp;<code>string1</code>&nbsp;equals&nbsp;<code>value1</code> 
			<code>filter=string1:value1</code></li>
			<li>Get all Concepts where&nbsp;<code>string1</code>&nbsp;equals&nbsp;<code>value1</code>&nbsp;and&nbsp;<code>string2</code>&nbsp;equals&nbsp;<code>value2</code> 
			<code>filter=string1:value1,string2:value2</code></li>
			<li>Get all Concepts where&nbsp;<code>string1</code>&nbsp;equals&nbsp;<code>value1</code>&nbsp;and&nbsp;<code>string2</code>&nbsp;does not equal&nbsp;<code>value2</code> 
			<code>filter=string1:value1,string2:-value2</code></li>
			<li>Get all Concepts created between&nbsp;<code>2020-01-01</code>&nbsp;and&nbsp;<code>2020-02-01</code> 
			<code>filter=createdDate:&gt;=2020-01-01,createdDate:2020-02-01</code></li>
			<li>Get all Concepts created or modified since&nbsp;<code>2020-01-01</code> 
			<code>filter=createdDate:&gt;=2020-01-01|lastModifiedDate:&gt;=2020-01-01</code></li>
			<li>Get all Concepts where<code>string1</code>&nbsp;equals&nbsp;<code>value1</code>&nbsp;or&nbsp;<code>value2</code> 
			<code>filter=string1:[value1,value2]</code></li>
			<li>Get all Concepts where&nbsp;<code>string1</code>&nbsp;equals&nbsp;<code>value1</code>&nbsp;and it was created or modified since&nbsp;<code>2020-01-01</code> 
			<code>filter=string1:value1,(createdDate:&gt;=2020-01-01|lastModifiedDate:&gt;=2020-01-01)</code></li>
			<li>Get all Concepts within 100 miles of coordinates (-40, 70) 
			<code>filter=_near((-40, 70), 100mi)</code></li>
			<li>Get all Concepts within the polygon with points (-40, 70), (-30, 60), (-35, 60) 
			<code>filter=_within((-40, 70) (-30, 60), (-35, 60))</code></li>
			<li>Get all Concepts within box with top left corner (-40, 70) and bottom right corner (-30, 60) 
			<code>filter=_within((-40, 70) (-30, 60))</code></li>
		</ul>
	</td>
</tr>
</tbody>
</table>

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="/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://secure.helpscout.net/api-docs">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="/knowledge-base/using-data-graphs-api/authentication">Authentication</a> for information on how to access your API key and generate an access token.

Using Data Graphs API

A Data Graphs user is assigned a team role. These roles are :<ul>
	
<li>Owner&nbsp;– 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.</li>	
<li>Administrator –&nbsp;can manage the account, users and all available actions, but cannot manage or see the subscription and billing screens.</li>	
<li>Developer&nbsp;– can&nbsp;read Datasets and events, write Datasets, export data, manage applications and web hooks to manage API integrations.</li>	
<li>Editor&nbsp;– An editor can read and write datasets and concepts and can export data</li>	
<li>Viewer&nbsp;– Has read only access, can only navigate and view data</li></ul>
	 You can 
	<a href="/knowledge-base/managing-your-account/managing-users">change a user's role</a> in the Manage Account screen.

Data Graphs users are managed by team members that have either the Owner or Administrator role. To manage your Data Graphs team and users, click on the user icon in the top right of the app nav bar:
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6071cff1e0324b5fdfd09a68/file-nx39PZzCST.png" style="width: 629px;">
	 From the menu choose Manage Account.<h2>Inviting users</h2>
	 Choose the Invitations link on the left hand menu. Click&nbsp;Invite New Members&nbsp;and then invite a new team member by entering their email address. You can choose the role they will have in your Data Graphs account.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6071d1378af76a714bfd5e7c/file-7gZlp29OOu.png" style="width: 613px;">
	 Invitations are time limited, so will expire after 48 hours. If an invitation has expired, you can renew it from this form.You can also delete invitations you no longer need.<h2>Changing a user's role</h2>
	 From the manage account screen click on the Members link in the left hand side menu. From here you see a list of your users, and change their role using the button to the right, selecting a new role from the drop down list presented. Find out <a href="/knowledge-base/managing-your-account/team-roles">here</a> what each role can do.
	 <img src="https://s3.amazonaws.com/helpscout.net/docs/assets/606c25df9b956f5f5cfe4092/images/6071d2a5e0324b5fdfd09a6d/file-WfFMA2dYBP.png" style="width: 667px;"><h2>Deleting&nbsp;a user</h2>
	 You can remove a user's Data Graphs access by using the Remove button on the same form.

Welcome to Data Graphs Support

Knowledge Base

Client SDK

API

Most popular Knowledge Base articles

Simple vocabularies

What is a Dataset?

About the API

Team roles