Journey Overview
Knowledge Search supports providers in retrieving longer-form, evidence-based content aimed at building or updating clinical understanding. Knowledge Search surfaces current research, synthesized concepts, and educational materials not directly tied to step-by-step clinical decisions. It is particularly useful for staying up to date with emerging knowledge, informing clinical reasoning, and exploring topics beyond rigid care protocols.
Getting Started
To get a broad understanding of the components within our data fabric, you can refer to our platform overview.
To get started in this journey, you will need:
- A Clinia workspace
- A Clinia service account (API Key)
- Ability to execute HTTP requests
- Some data to ingest
We will go over a simple single collection use case for now. Make sure to refer to the documentation if you want to tailor the Data Fabric configuration to your exact use case.
For the sake of this journey, we’ll leverage the following sample article data:
{
"doi": "10.1186/1750-1172-8-79",
"abstract": "# Olmsted Syndrome: Exploration of the Immunological Phenotype\n\nThis study explores the immunological aspects of **Olmsted Syndrome (OS)**, a rare congenital skin disorder characterized by severe, mutilating keratoderma and periorificial hyperkeratotic lesions. The condition is typically associated with recurrent skin infections.\n\n## Key Findings\n\n- **Genetic Mutation:** \n The patient, an 18-year-old male, exhibited a previously unreported de novo TRPV3 mutation (*Gly573Ala*), known to cause hyperactivation of the TRPV3 ion channel. This supports TRPV3's central role in OS.\n\n- **Clinical Presentation:** \n - Early-onset, progressive dermatological symptoms \n - Severe physical impairment (e.g., digit contractures, alopecia) \n - Lesions responsive to environmental triggers \n - Resistance to various treatment modalities\n\n- **Immunological Profile:** \n - Frequent dermal infections (*e.g., Candida albicans*) \n - Elevated serum IgE (hyper IgE) \n - Chronic peripheral eosinophilia \n - Increased follicular helper T (Tfh) cells in peripheral blood \n - Normal T cell responses and granulocyte function\n\n## Conclusions\n\nThis is the first comprehensive analysis showing systemic immune dysregulation in Olmsted Syndrome. The findings raise two potential disease models:\n\n1. **Primary keratinocyte-driven pathology:** \n Hyperactive TRPV3 disrupts the skin barrier, leading to secondary immune dysregulation.\n\n2. **Primary immunological dysfunction:** \n TRPV3 mutations affect Langerhans cells, triggering localized autoimmunity and subsequent skin symptoms.\n\nThe study emphasizes the need for further research to clarify OS mechanisms and guide potential immunomodulatory treatments."
"content": "...",
"title": "Olmsted syndrome: exploration of the immunological phenotype"
}
Workspace Configuration
To leverage semantic search and Clinia’s query understanding capabilities, you will need a collection with a vectorizer ingestion pipeline.
Create a Data Source
Documentation
Currently, the only data source type available is a Registry. To create your {name} data source, run the following request:
curl --location --request PUT 'https://api.{workspaceId}.clinia.cloud/catalog/v1/sources/my-data' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE' \
--data '{
"type": "registry"
}'
Create your article Profile
Documentation
Before ingesting your data, we need to define the schema of the properties representing your data model. Given our sample article, here is what the article profile should look like:
curl --location --globoff --request PUT 'https://api.{workspaceId}.clinia.cloud/sources/my-data/v1/collections/article' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE' \
--data '{
"type": "resources",
"profile": {
"properties": {
"doi": { "type": "symbol" },
"title": { "type": "symbol" },
"content": { "type": "markdown" },
"abstract": { "type": "markdown" }
}
}
}'
Ingestion Pipeline
Documentation
Now into the fun stuff. To leverage semantic search capabilities, you will need to augment your raw data using our various processors.
To properly support semantic search, we will need a Vectorizer processor to create semantic representations of the article passages.
The Vectorizer takes as input symbol data types and returns vectors (arrays of float-value points) representing your data in the vector space. This vector space is built in such a way that semantically related ideas or sentences (e.g. “diabetes” and “hyperglycemia”) are closer together and dissimilar ideas (e.g. “banana” and “psychologist”) are farther apart.
In the context of knowledge search, we will focus on processing the content and the abstract property to be meaningful and interpretable. Think of it this way: for which attributes is keyword search limiting? Here is an example of that might look like for article search:
{
"steps": [
// will create a semantic representation of the 'content' into 'content.vector'
{
"type": "VECTORIZER",
"vectorizer": {
"inputProperty": "content",
"propertyKey": "vector",
"modelId": "text-embedding-004",
"provider": "google",
"dimensions": 768
}
},
// will create a semantic representation of the 'abstract' into 'abstract.vector'
{
"type": "VECTORIZER",
"vectorizer": {
"inputProperty": "abstract",
"propertyKey": "vector",
"modelId": "text-embedding-004",
"provider": "google",
"dimensions": 768
}
}
]
}
curl --location --globoff --request PUT 'https://api.{workspaceId}.clinia.cloud/catalog/sources/my-data/v1/collections/article/pipeline' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE' \
--data '{
"steps": [
{
"type": "VECTORIZER",
"vectorizer": {
"inputProperty": "content",
"propertyKey": "vector",
"provider": "google",
"modelId": "text-embedding-004",
"dimensions": 768
}
},
{
"type": "VECTORIZER",
"vectorizer": {
"inputProperty": "abstract",
"propertyKey": "vector",
"provider": "google",
"modelId": "text-embedding-004",
"dimensions": 768
}
}
]
}'
Ingesting data
Once everything is configured, you can create your records using our Standard or Bulk API. Using the Bulk API, here is what that can look like:
curl --location --globoff --request PUT 'https://api.{workspaceId}.clinia.cloud/catalog/sources/my-data/v1/resources/bulk' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE' \
--data '{
"operations": [
{
"action": "CREATE",
"create": {
"type": "article",
"doi": "10.1186/1750-1172-8-79",
"abstract": "# Olmsted Syndrome: Exploration of the Immunological Phenotype\n\nThis study explores the immunological aspects of **Olmsted Syndrome (OS)**, a rare congenital skin disorder characterized by severe, mutilating keratoderma and periorificial hyperkeratotic lesions. The condition is typically associated with recurrent skin infections.\n\n## Key Findings\n\n- **Genetic Mutation:** \n The patient, an 18-year-old male, exhibited a previously unreported de novo TRPV3 mutation (*Gly573Ala*), known to cause hyperactivation of the TRPV3 ion channel. This supports TRPV3s central role in OS.\n\n- **Clinical Presentation:** \n - Early-onset, progressive dermatological symptoms \n - Severe physical impairment (e.g., digit contractures, alopecia) \n - Lesions responsive to environmental triggers \n - Resistance to various treatment modalities\n\n- **Immunological Profile:** \n - Frequent dermal infections (*e.g., Candida albicans*) \n - Elevated serum IgE (hyper IgE) \n - Chronic peripheral eosinophilia \n - Increased follicular helper T (Tfh) cells in peripheral blood \n - Normal T cell responses and granulocyte function\n\n## Conclusions\n\nThis is the first comprehensive analysis showing systemic immune dysregulation in Olmsted Syndrome. The findings raise two potential disease models:\n\n1. **Primary keratinocyte-driven pathology:** \n Hyperactive TRPV3 disrupts the skin barrier, leading to secondary immune dysregulation.\n\n2. **Primary immunological dysfunction:** \n TRPV3 mutations affect Langerhans cells, triggering localized autoimmunity and subsequent skin symptoms.\n\nThe study emphasizes the need for further research to clarify OS mechanisms and guide potential immunomodulatory treatments."
"content": "...",
"title": "Olmsted syndrome: exploration of the immunological phenotype"
}
]
}'
taskId from the response that the request above will give you to track the status of the bulk ingestion task request. Use this request to do so:
curl -X GET "https://$CLINIA_WORKSPACE/sources/my-data/v1/tasks/{taskId}?withReceipts=true" \
-H "X-Clinia-API-Key: $CLINIA_TOKEN" \
-H "Content-Type: application/json"
Searching your collection
Documentation
Once the ingestion is complete, you are now ready to search your collection!
You can use the Search API. Here is one example of a query that uses the knn operator for your semantic fields:
curl --request POST \
--url https://api.{workspaceId}.clinia.cloud/sources/my-data/v1/collections/article/query \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"perPage": 20,
"query": {
"or": [
{
"knn": {
"content.vector": {
"value": "What is the disease of Olmsted?"
}
}
},
{
"knn": {
"abstract.vector": {
"value": "What is the disease of Olmsted?"
}
}
}
]
},
"highlighting": ["content.vector", "abstract.vector"]
}'
highlighting support, to tell you why a given result was relevant. Using highlighting, you will be able to tell which of the fields or passages within each article hit was most relevant. This is particularly useful for display purposes, but also to generate the best answer possible using our Summarization API.
