Skip to main content

​
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 Health-Grade Search (HGS) 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:
  1. A Clinia workspace
  2. A Clinia service account (API Key)
  3. Ability to execute HTTP requests
  4. 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 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": 45.5,
    "latitude": -72.316666
  }
}

​
Workspace Configuration

To leverage semantic search and Clinia’s query understanding capabilities, you will need a HGS partition instead of our Standard partition offering.

​
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://{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

Documentation 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://{workspaceId}.clinia.cloud/sources/my_data/v1/profiles/provider' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE' \
--data '{
  "type": "ROOT",
  "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.

​
Create your Data Partition

Documentation Once your profile is created, we can now create the data partition, which is a virtual, searchable view of your data. Let’s create a provider_search partition for your provider search application. Specifying the HEALTH_GRADE_SEARCH is key to indicating that we want this partition to be built so that we can use semantic search functionalities instead of regular keyword search. 
curl --location --globoff --request PUT 'https://{workspaceId}.clinia.cloud/catalog/v1/partitions/provider_search/pipeline' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE' \
--data '{
  "modules": {
    "search": "HEALTH_GRADE_SEARCH"
  },
  "source": {
    "type": "DATA_SOURCE",
    "key": "my_data",
    "collections": [
      {
        "key": "provider"
      }
    ]
  }
}'

​
Ingestion Pipeline

Documentation Now into the fun stuff. To leverage Clinia’s HGS engine, 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": "mte-base.1"
      }
    },
    // will embed the fieldsOfInterest into the fieldsOfInterest.vector enriched field
    {
      "type": "VECTORIZER",
      "vectorizer": {
        "inputProperty": "fieldsOfInterest",
        "propertyKey": "vector",
        "modelID": "mte-base.1"
      }
    }
  ]
}
You can add this pipeline to your collection with the following request: 
curl --location --globoff --request PUT 'https://{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": "embed-v1"
      }
    },
    {
      "type": "VECTORIZER",
      "vectorizer": {
        "inputProperty": "fieldsOfInterest",
        "propertyKey": "vector",
        "modelID": "embed-v1"
      }
    }
  ]
}'
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://{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"
        ],
        "geoPoint": {
          "longitude": 45.5,
          "latitude": -72.316666
        }
      }
    }
  ]
}'
You can use the bulkId from the response that the request above will give you to track the status of the bulk ingestion request. Use this request to do so: 
curl --location --globoff --request GET 'https://{workspaceId}.clinia.cloud/catalog/sources/my_data/v1/resources/bulk/bulkId?withReceipts=true' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Clinia-Api-Key: YOUR_API_KEY_HERE'
Once fully processed, the bulk task with be marked as successful and the records propagated to the relevant partitions.

​
Querying your HGS Partition

Documentation Once the ingestion is complete, you are now ready to use your HGS partition! 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://.clinia.cloud/partitions/provider_search/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.

​
Query Understanding

You might be asking yourself how to determine which search operator to use, or which path you should target. Clinia’s Search API also proposes a semanticQuery parameter in which you can select the type of search experience you are implementing at query time and let Clinia’s Query Intelligence do the rest for you using the provided query and profile properties. 
curl --request POST \
     --url https://.clinia.cloud/partitions/provider_search/v1/collections/provider/query \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "semanticQuery": {
			"type": "provider-search" | "knowledge-search" | "patient-chart-search",
      "text": "give me all physiotherapists in New Jersey"
		},
}
'
⌘I