---
title: "Import"
canonical: "https://help.starhive.com/space/DOC/286621697/Import"
format: markdown
---
## About
This feature allows importing data from various sources into Starhive. It supports creating or updating multiple objects in a specific Starhive *[Type](https://help.starhive.com/space/DOC/177537026/Type)*. This documentation will guide you through the process to ensure a successful import.
## Importing data
Before importing the data you would need to follow some steps to create a Connection.
### Select and configure a Source
The source refers to the origin of the data. In order to get the data you need to provide the source configuration which depends on the source. Select your source type from the list and fill out all the necessary configuration fields.
> ℹ️ For some source types, we can’t determine if the source configuration is faulty or not before proceeding.
### Map Data Stream
After creating a source configuration, the next step is to map a stream to a Starhive *Type*. A **stream** represents an entity type in the source system.
For example, if your source is a relational database, a stream would correspond to a table. To begin mapping, select a stream and a Starhive *Type*—the available attributes will then be displayed.
Attributes configured as **required** will be marked with an asterisk (*). However, mapping them is not strictly necessary, allowing flexibility for running imports intended for updates.
#### Supported Attribute Types
We **support** following attribute types when importing:
| **Attribute type**
*(the name of the attribute type)* | **Description**
*(anything need to know when importing)* |
| --- | --- |
| **Text**
*Value Type: STRING* | *Any text supporting the rules of the attribute* |
| **Rich Text**
*Value Type: STRING* | *Any text with markdown syntax supporting the rules of the attribute* |
| **Integer**
*Value Type: INTEGER* | *Any Integer supporting the rules of the attribute* |
| **Decimal**
*Value Type: DECIMAL* | *Any Decimal supporting the rules of the attribute* |
| **Option**
*Value Type: STRING* | *Any text supporting the rules of the attribute*. Needs to be a configured option value |
| **Date**
*Value Type: DATE* | *Value needs to be in format:*
- `yyyy-MM-dd` // ISO
- `dd/MM/yyyy` // European
- `MM-dd-yyyy` // US
- `yyyy/MM/dd` // Alternative ISO |
| **DateTime**
*Value Type:* *DATETIME* | *Value needs to be in format:*
- `yyyy-MM-dd HH:mm:ss` // ISO
- `dd/MM/yyyy HH:mm:ss` // European
- `MM-dd-yyyy HH:mm:ss` // US
- `yyyy/MM/dd HH:mm:ss` // Alternative ISO |
| **URL**
*Value Type: STRING* | *Any URL supporting the rules of the attribute* |
| **Email**
*Value Type: STRING* | *Any email supporting the rules of the attribute* |
| **Boolean**
*Value Type: BOOLEAN* | *Any boolean supporting the rules of the attribute* |
| **Reference**
*Value type: REFERENCE* | *Value represented by an object label. Values needs to support the rules of the attribute* |
| **IP Address**
*Value Type: IP ADDRESS* | *Any IP Address supporting the rules of the attribute* |
| **Rating**
*Value Type: DECIMAL* | *Any decimal value supporting the rules of the attribute* |
| **USER**
*Value Type: STRING* | *Value represented by user email.* |
| **PRIORITY**
*Value Type: STRING* | *Any string value supporting the rules of the attribute* |
We currently **do not support** following attribute types:
- Avatar (System Image)
- Location
- Media
- Workflow
Additionally, some attributes, such as last updated, are generally not allowed for user modification and are therefore unsupported for import. For the latest details, please read our documentation about *[Attribute Types](https://help.starhive.com/space/DOC/177340428/Attribute)**.*
#### Object Identifier
While *[Object](https://help.starhive.com/space/DOC/180879361/Objects)* creation only requires the mapping to be in place - updating *Objects* requires an identifier mapping. An identifier is the field used to determine which *Object* should be updated. If your Starhive setup stores external IDs, you can map them directly to Starhive *Objects*. Additionally, you can use multiple identifiers when a single unique value isn’t available—this helps ensure accurate object matching.
**Example**
Suppose you have a Postgres source with a table containing all the cities in the world. Using only the **city name** *Attribute* as an identifier wouldn’t work, as the same city name can exist in multiple countries. In this case, you would use a combination of **country name** and **city name** as the identifier.
To function correctly, the chosen identifier (or combination of fields) must be **unique**. If a match is found, the existing object is updated; otherwise, a new object is created.
**Recommendation:** Always use an identifier when importing to prevent duplicate objects.
#### **Mapping reference attributes**
When mapping an *Attribute* of *Object Reference* type, you need to choose an identifier for the referenced *Object*.
**Example**
Suppose you have two *Types*: **Country** and **City**. The **City** *Type* has an object reference attribute mapped to **Country**. In this scenario, all countries already exist in the **Country** *Type*, and we are now importing cities from a **City** stream into Starhive.
The **City** stream has a field called `country`, where each city entry contains a country name. To correctly map this name to an existing **Country** *Object* in Starhive, we need to specify which attribute in **Country** serves as the identifier. In this case, we use the `name` *Attribute* in **Country** to establish the reference.
Be cautious when importing self-reference or data with cyclic dependency
When importing references, the referenced object must already exist in Starhive to establish the connection. If a cyclic dependency is encountered during import, you will be notified through a UI notification. While we will make our best effort to import the data despite these dependencies, the most reliable approach is to structure your imports proactively.
**Best Practice for Circular References:**
When you have circular dependencies between different types (e.g., Company references Employee, Employee references Department, Department references Company), arrange your connection syncing order strategically:
1. **First sync**: Import one type in the chain without references (e.g., Companies)
2. **Later syncs**: Import remaining types that reference the previously imported data
**Alternative for Self-References:**
For self-referencing scenarios (e.g., Employee has a "Manager" field that references another Employee), use a multi-stage approach:
1. **First pass**: Import all Employee objects without the Manager references
2. **Second pass**: Update Employee objects to establish Manager relationships
This staged approach ensures references can be correctly assigned without missing dependencies.
Note: Starhive automatically handles dependency resolution by running imports in optimized phases. User intervention is only needed when circular dependencies are detected.
### Run the import
After setting up an import, we recommend running it manually once to verify that it meets your expectations.
The import status is displayed in the Import Connections list view.
[PENDING] - The import connection is created but has not yet run.
[Syncing] – The import is currently in progress.
[COMPLETED] – The import finished successfully.
[COMPLETED] – The import finished, but some objects could not be imported due to attribute value violations or other data issues.
[Failed] – The import completed but encountered errors.
[Cancelled] – The import was manually stopped by a user.
[SKIPPED] – The import was skipped as it was disabled.
From the list view, you can navigate to the **sync log** for more details on a job. If the sync fails, you can download a document containing detailed error information.
### Error report
The error report includes different type of errors. The *Object* validation errors are aggregated, meaning that if multiple errors of the same type occur for the same operation (create or update) and attribute mapping, they will be grouped together as:
```
Error Type: CHARACTER_LIMIT
Operation: CREATE
Attribute: Name
Count: 10
Example:
{
Name: John Doe,
Age: 34
}
-----------
```
In this example we can see that 10 *Objects* in the import that were about to be created had issues when processing their Name values due to the a character limit in the attributes configuration. In the Example field we can see that one of the failed rows was the John Doe object.
If an error originates from the source system, it will be presented as logs with a stack trace.
### Scheduled Imports
Automate data synchronization to keep your data current without manual intervention. Choose from predefined schedules:
**Schedule Options:** Manual (on-demand only), Every 12 Hours (twice daily), Every Day (daily updates), Every Week (weekly sync), Every Month (monthly refresh), Every Year (annual imports).
Scheduled imports automatically handle dependencies and run as background tasks for seamless data updates.