Provider Search
How-to setup a provider search experience for your patient portal.
Journey Overview
Provider search empowers patients and providers to efficiently find and connect with the right professionals or services. Leveraging semantic capabilities, it ensures personalized, accurate, context-aware and complete results. For patients, it offers autonomy and convenience. For providers, it streamlines referrals. For payers and health systems, it improves care coordination and optimizes network utilization.
If the above resonates with your use case, you are at the right place. Let’s dive into how you can deploy your very own provider search experience using Clinia’s technology.
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 provider 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 provider data:
{
"id": "123456",
"gender": "female",
"name": {
"prefix": [
"Miss"
],
"given": [
"Kim"
],
"family": "Ford",
"suffix": [],
"use": "usual"
},
"specialities": [
"Rehabilitation medicine"
],
"fieldsOfInterest": [
"Patient care management",
"Blood analysis",
"Occupational health services",
"Physical therapy evaluation",
"Radiology service",
"Continuity of patient care",
"CT scanning of the spine",
"Consultation",
"PT"
],
"clientele": [
"pediatric"
],
"position": {
"longitude": -72.316666,
"latitude": 45.5
}
}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
Currently, the only data source type available is a Registry. To create your my-data data source, run the following request:
curl --location --request PUT 'https://api.{workspaceId}.clinia.cloud/catalog/v1/sources/{name}' \--header 'Content-Type: application/json' \--header 'Accept: application/json' \--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE' \--data '{ "type": "registry"}'Create your provider Profile
Before ingesting your data, we need to define the schema of the properties representing your data model. Given our sample provider, here is what the provider profile should look like:
curl --location --globoff --request PUT 'https://api.{workspaceId}.clinia.cloud/sources/my-data/v1/collections/provider' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE' \
--data '{
"type": "resources",
"profile": {
"properties": {
"name": {
"type": "humanname"
},
"gender": {
"type": "code"
},
"specialities": {
"type": "array",
"items": {
"type": "symbol"
}
},
"fieldsOfInterest": {
"type": "array",
"items": {
"type": "symbol"
}
},
"clientele": {
"type": "array",
"items": {
"type": "symbol"
}
},
"position": {
"type": "geopoint"
}
}
}
}'Source profiles definition uses the Clinia Data Types System and relies on composition to allow a truly flexible data modelling experience.
Ingestion Pipeline
Now into the fun stuff. To leverage semantic search capabilities, you will need to augment your raw data using our various processors. For our example, we will need a Vectorizer processor to create semantic representations of the provider attributes.
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 (e.g. “diabetes” and “hyperglycemia”) are closer together and dissimilar ideas (e.g. “banana” and “psychologist”) are farther apart.
In the context of provider search, targeting specialities and fieldsOfInterest makes the most sense given that these are the traits that best inform the medical capabilities of the provider. These traits also require deep semantic understanding for them to be most useful. Think of it this way: for which attributes is keyword search limiting? Here is an example of that might look like for provider search:
{
"steps": [
// will embed the specialities into the specialities.vector enriched field
{
"type": "VECTORIZER",
"vectorizer": {
"inputProperty": "specialities",
"propertyKey": "vector",
"modelId": "text-embedding-004",
"provider": "google",
"dimensions": 768
}
},
// will embed the fieldsOfInterest into the fieldsOfInterest.vector enriched field
{
"type": "VECTORIZER",
"vectorizer": {
"inputProperty": "fieldsOfInterest",
"propertyKey": "vector",
"modelId": "text-embedding-004",
"provider": "google",
"dimensions": 768
}
}
]
}You can add this pipeline to your collection with the following request:
curl --location --globoff --request PUT 'https://api.{workspaceId}.clinia.cloud/catalog/sources/my-data/v1/collections/provider/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": "specialities",
"propertyKey": "vector",
"modelId": "text-embedding-004",
"provider": "google",
"dimensions": 768
}
},
{
"type": "VECTORIZER",
"vectorizer": {
"inputProperty": "fieldsOfInterest",
"propertyKey": "vector",
"modelId": "text-embedding-004",
"provider": "google",
"dimensions": 768
}
}
]
}'Now that your ingestion pipeline and steps are set up, your data source is ready to receive data. Incoming records will be processed through the pipeline and their data augmented before being persisted in the system.
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": "provider",
"id": "123456",
"gender": "female",
"name": {
"prefix": [
"Miss"
],
"given": [
"Kim"
],
"family": "Ford",
"suffix": [],
"use": "usual"
},
"specialities": [
"Rehabilitation medicine"
],
"fieldsOfInterest": [
"Patient care management",
"Blood analysis",
"Occupational health services",
"Physical therapy evaluation",
"Radiology service",
"Continuity of patient care",
"CT scanning of the spine",
"Consultation",
"PT"
],
"clientele": [
"pediatric"
],
"position": {
"longitude": -72.316666,
"latitude": 45.5
}
}
}
]
}'You can use the 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"Once fully processed, the bulk task will be marked as successful and the records available for search in your collection.
Querying your collections
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 and a match operator for a name:
curl --request POST \
--url https://api.{workspaceId}.clinia.cloud/sources/my-data/v1/collections/provider/query \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"perPage": 20,
"query":{
"or": [
{
"match": {
"name.given": {
"value": "Kim",
"type": "word"
}
}
},
{
"knn": {
"specialities.vector": {
"value": "physiotherapy"
}
}
}
]
}
}
'You can find details about the API response here. The API comes with highlighting support, to tell you why a given result was relevant.