This guide covers a direct connection to the Honeydew API using GraphQL.It is also possible to use Honeydew APIs with a
Snowflake Connection,
by calling the Snowflake Native Application API.
Public GraphQL API is not enabled by default. To enable for your organization, please contact support@honeydew.ai.
Use Cases
Embedded Analytics
The GraphQL API can be used to build embedded analytics applications that leverage the semantic layer. This allows you to build custom applications that use the semantic layer to generate queries and retrieve data.Building custom AI analyst applications
The GraphQL API can be used to build custom AI analyst applications that leverage the semantic layer to answer user questions in natural language.Metadata Sharing
The GraphQL API can be used to share metadata with other applications or services. For example, you can use the GraphQL API to share metadata with a data catalog or a data governance tool, or to import metadata from another system into Honeydew.BI Integration
The GraphQL API can be used to publish metadata to BI tools, such as Tableau, Power BI, Thoughtspot, and more.Development and Testing
The GraphQL API can be used to develop and test semantic layer definitions. Developers can use their favorite development tools to edit the semantic layer definitions, push them directly to git, and use the GraphQL APIs to validate the definitions. These validations can also be integrated into CI/CD pipelines to ensure that the semantic layer definitions are valid before deploying them to production.Usage
Security
You can use the GraphQL API with an API Key and Secret. You cannot use the GraphQL API with a Honeydew username and password.Different API queries and mutations require different permissions. Therefore, in order to follow
the principal of least privileges as a best practice, you may need to create different API keys for different use cases.Each query or mutation below specifies the required permissions.
It is recommended to restrict API access to specific IP addresses or ranges,
by using the IP Access Control feature.
To set up IP Access Control, please contact support@honeydew.ai.
API Endpoint
The default API endpoint ishttps://api.honeydew.cloud/api/public/v1/graphql
.
If your organization uses a custom hostname for the API connection,
you can locate it in the Honeydew UI, under the API section in Settings.
Headers
The following custom Honeydew headers can be used in the API requests:X-Honeydew-Client
: A string that identifies the client making the request. Use it to identify the client in Honeydew logs and query history, for audit, debugging and support purposes.X-Honeydew-Workspace
: The name of the workspace to use for the request. This is required for most queries and mutations that operate on a specific workspace.X-Honeydew-Branch
: The name of the branch to use for the request. This is required for most queries and mutations that operate on a specific branch.
Rate Limiting
The Public API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per user (or per API key) and are enforced according to industry standards. Default Rate Limit: 60 calls per user/key per minute Response Headers: The API provides rate limit information through standard HTTP response headers:RateLimit-Limit
: The maximum number of requests allowed per time windowRateLimit-Remaining
: The number of requests remaining in the current time windowRateLimit-Reset
: The timestamp when the rate limit will reset (in Unix epoch seconds)
Monitor these headers in your API responses to implement proper rate limiting in your applications and avoid hitting rate limits unexpectedly.
When you exceed the rate limit, the API will return a
429 Too Many Requests
HTTP status code. Implement exponential backoff and retry logic in your applications to handle rate limiting gracefully.If you need to increase your rate limits beyond the default, please contact support@honeydew.ai to discuss your requirements.
API integration example
Below we have provided API integration examples for Python, JavaScript and cURL. The API can be used with any programming language that supports HTTP requests.To learn more about GraphQL, you can refer to the GraphQL documentation
- Python
- JavaScript
- cURL
This example uses the
requests
library to make HTTP requests to the Honeydew API.
To install it, run:The above examples are basic and do not include error handling.
In production code, you should handle errors and exceptions appropriately.
We recommended using a graphql client library for more complex queries and mutations.
GraphQL API Reference
Workspaces and Branches
List Workspaces
List Workspaces
Workspace/Branch Headers: Not requiredPermissions: Viewer or higher
GraphQL Query
Create Workspace Branch
Create Workspace Branch
This mutation creates a new branch in the specified workspace.Workspace/Branch Headers: Not requiredPermissions: Editor or higher
GraphQL Mutation
Successful Result Example
Error Example
Reload Workspace
Reload Workspace
This mutation reloads the specified workspace from Git.Workspace/Branch Headers: RequiredPermissions: Viewer or higher
GraphQL Mutation
Result Example
Reload All Workspaces
Reload All Workspaces
This mutation reloads all workspaces from Git.Workspace/Branch Headers: Not requiredPermissions: Viewer or higher
GraphQL Mutation
Result Example
Reload Workspace for All Users
Reload Workspace for All Users
This mutation reloads a workspace from Git for all users.
This is useful for ensuring that all users see the latest changes in the workspace.Workspace/Branch Headers: RequiredPermissions: Admin
GraphQL Mutation
Result Example
Reload All Workspaces for All Users
Reload All Workspaces for All Users
This mutation reloads all workspaces from Git for all users.
This is useful for ensuring that all users see the latest changes in all workspaces,
in particular after a workspace was added or deleted.Workspace/Branch Headers: Not requiredPermissions: Admin
GraphQL Mutation
Result Example
Querying Schema
List Entities
List Entities
Workspace/Branch Headers: RequiredPermissions: Viewer or higher
GraphQL Query
Get Entity By Name
Get Entity By Name
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
entity_name
: The name of the entity to retrieve
GraphQL Query
Get Entity Field By Name
Get Entity Field By Name
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
entity_name
: The name of the entity to retrieve the field fromname
: The name of the field to retrieve
GraphQL Query
List Domains
List Domains
Workspace/Branch Headers: RequiredPermissions: Viewer or higher
GraphQL Query
Get Domain By Name
Get Domain By Name
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
name
: The name of the domain to retrieve
GraphQL Query
List Global Parameters
List Global Parameters
Workspace/Branch Headers: RequiredPermissions: Viewer or higher
GraphQL Query
Get Global Parameter By Name
Get Global Parameter By Name
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
name
: The name of the global parameter to retrieve
GraphQL Query
List Dynamic Datasets
List Dynamic Datasets
Workspace/Branch Headers: RequiredPermissions: Viewer or higher
GraphQL Query
Get Dynamic Dataset By Name
Get Dynamic Dataset By Name
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
name
: The name of the dynamic dataset to retrieve
GraphQL Query
Modifying Schema
Create Object
Create Object
Workspace/Branch Headers: RequiredPermissions: Editor or higherParameters:
yaml
: The YAML definition of the object to create. See references for YAML schema here.force_with_error
:- If false, the mutation will fail if the deletion causes the workspace to become invalid (For example, if the object is used by another object in the workspace).
- If true, the mutation will delete the object even if it causes the workspace to become invalid. This is useful if you are performing a set of changes that will eventually make the workspace valid again.
name
, error
, etc.GraphQL Mutation
Update Object
Update Object
Workspace/Branch Headers: RequiredPermissions: Editor or higherParameters:
yaml
: The YAML definition of the object to update. See references for YAML schema here.object_key
: The key of the object to update. This is theobject_key
field that can be retrieved in any query on objects.force_with_error
:- If false, the mutation will fail if the deletion causes the workspace to become invalid (For example, if the object is used by another object in the workspace).
- If true, the mutation will delete the object even if it causes the workspace to become invalid. This is useful if you are performing a set of changes that will eventually make the workspace valid again.
name
, error
, etc.GraphQL Mutation
Delete Object
Delete Object
Workspace/Branch Headers: RequiredPermissions: Editor or higherParameters:
object_key
: The key of the object to delete.force_with_error
:- If false, the mutation will fail if the deletion causes the workspace to become invalid (For example, if the object is used by another object in the workspace).
- If true, the mutation will delete the object even if it causes the workspace to become invalid. This is useful if you are performing a set of changes that will eventually make the workspace valid again.
GraphQL Mutation
Queries
Get SQL for adhoc query
Get SQL for adhoc query
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
yaml_text
: YAML definition of a dynamic dataset, which represents a query. For more information on the YAML format, see Dynamic Dataset YAML.domain
: The name of the domain to use for the query.
domain
: The domain to use for the query (if applicable), as extracted from the SQL query.dwh_role
: The Snowflake role to use for the query, based on the definitions in the workspace, branch and the domain.dwh_warehouse
: The Snowflake warehouse to use for the query, based on the definitions in the workspace, branch and the domain.sql
: A list of the actual Snowflake SQL queries to run, translated from the provided SQL query by the Honeydew semantic layer. Note that there can be multiple sql statements to run, for example - there might be aSET
statement to set values for parameters used in the sql query.
GraphQL Query
Translate SQL interface query to Snowflake SQL
Translate SQL interface query to Snowflake SQL
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
sql
: The SQL query to translate. This should be a valid SQL query in Trino dialect. For more information, see SQL Interface documentation.
domain
: The domain to use for the query (if applicable), as extracted from the SQL query.dwh_role
: The Snowflake role to use for the query, based on the definitions in the workspace, branch and the domain.dwh_warehouse
: The Snowflake warehouse to use for the query, based on the definitions in the workspace, branch and the domain.sql
: A list of the actual Snowflake SQL queries to run, translated from the provided SQL query by the Honeydew semantic layer. Note that there can be multiple sql statements to run, for example - there might be aSET
statement to set values for parameters used in the sql query.
GraphQL Query
AI
Plaintext To Data Using AI
Plaintext To Data Using AI
This query allows you to ask a question to the AI and get a response in the form of a dynamic dataset
and a SQL query.
You can use this to ask questions about your data and get a response in a structured format.
You can subsequently run the SQL query to get the data.Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
question
: The data question to ask the AIdomain_name
: The name of the domain to use for the questioncortex_llm_name
: The name of the LLM to use for the question, ornull
to use the default LLM configured in the domain.default_results_limit
: The default limit for the number of results to returntemperature
: The temperature to use for the LLM response. Passnull
to use the default temperature configured.max_tokens
: The maximum number of tokens to return in the LLM response. Passnull
to use the default max tokens configured.conversation_id
: The ID of the conversation to use for the question. Can be used in subsequent questions to continue the conversation with follow-up questions. Subsequent questions with sameconversation_id
will use the context of the entire thread. Ifnull
is provided, a new conversation will be created.include_judge
: Iftrue
, the response will include an explanation and correctness evaluation of the LLM response.
error
: An error message if the question failed, ornull
if the question succeeded.input_tokens
: The number of input tokens used by the LLM.judge
: An object containing the explanation and correctness evaluation of the LLM response, ifinclude_judge
istrue
.explanation
: The explanation of the LLM response.is_correct
: A status indicating whether the LLM response is correct. Can beyes
,no
,partially
orunknown
.runtime_ms
: The runtime of the LLM response in milliseconds.
llm_response
: The raw LLM response as a string.llm_response_json
: The LLM response as a JSON object, if applicable.output_tokens
: The number of output tokens generated by the LLM.dynamic_dataset
: The dynamic dataset generated by the LLM response, if applicable.question_id
: The ID of the question.runtime_ms
: The runtime of the question in milliseconds.sql
: The SQL query generated by the LLM response, if applicable.
GraphQL Query
BI Integration
Get Looker LookML For Domain
Get Looker LookML For Domain
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
domain
: The domain to retrieve the Looker LookML for
GraphQL Query
Get ThoughtSpot TML For Domain
Get ThoughtSpot TML For Domain
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
domain
: The domain to retrieve the ThoughtSpot TML forconnection_name
: The name of the Honeydew connection in ThoughtSpot to use
GraphQL Query
Get Lightdash Model For Domain
Get Lightdash Model For Domain
Workspace/Branch Headers: RequiredPermissions: Viewer or higherParameters:
domain
: The domain to retrieve the Lightdash model for
GraphQL Query