{"id":686,"date":"2020-10-08T11:47:23","date_gmt":"2020-10-08T18:47:23","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=686"},"modified":"2020-10-08T11:47:23","modified_gmt":"2020-10-08T18:47:23","slug":"search-app-with-cognitive-search","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/search-app-with-cognitive-search\/","title":{"rendered":"Add search to an application with the new Azure Cognitive Search SDK"},"content":{"rendered":"

<\/p>\n

If you’ve ever used an application that didn’t include search functionality, you’ll know how important search is to help you find what you’re looking for. Whether you’re building an e-commerce site, an internal website for your company, or any other type of application, it’s important to help users quickly find what they’re looking for and search does just that.<\/p>\n

With Azure Cognitive Search<\/a> and the Azure SDKs<\/a>, you can build a search application from scratch or infuse search into an existing application in just a few minutes. This blog post will walk you through the process of building and deploying a simple search application with Azure Cognitive Search and the new Azure SDK for Javascript\/Typescript<\/a>. We’ll first create an Azure Function to encapsulate the search client and query logic. After that, we’ll deploy a React template using Azure Static Web Apps to integrate our Azure Functions with a front-end.<\/p>\n

This sample uses a demo search service and index hosted by Microsoft. To use this sample, you just need an IDE and access to an Azure subscription.<\/p>\n

By the end of this post, you’ll know how to deploy a sample application that looks like this:<\/p>\n

\"Screenshot<\/p>\n

You can find the full code for this blog post at: aka.ms\/search-react-template<\/a>.<\/p>\n

You can find the demo website at: aka.ms\/azs-good-books<\/a>.<\/p>\n

Thinking through the search user experience<\/h2>\n

At a high level, there are three pieces of search functionality we need to add to an application to provide an intuitive search experience.<\/p>\n

    \n
  1. Search<\/strong> – provides search functionality for the application.<\/li>\n
  2. Suggest<\/strong> – provides suggestions as the user is typing in the search bar.<\/li>\n
  3. Document Lookup<\/strong> – looks up a document by id to retrieve all of its contents for the details page.<\/li>\n<\/ol>\n

    Building the application<\/h2>\n

    Connecting to a search index<\/h3>\n

    For this blog post, I’ve created a search index using the goodbooks-10k dataset<\/a> that that is publicly available using the following connection information:<\/p>\n

    \"SearchServiceName\": \"azs-playground\",\n\"SearchIndexName\": \"good-books\",\n\"SearchAPIKey\": \"03097125077C18172260E41153975439\"\n<\/code><\/pre>\n
    The index consists of 10,000 popular books that we’ll search over in our application.<\/p>\n
    Forking the repo<\/h3>\n
    If you want to follow along with this blog post, navigate to the repo<\/a> and select Use this template<\/strong>.<\/p>\n
    \"Use<\/p>\n
    This will create your own copy of the code that you can deploy and edit as you please.<\/p>\n
    Building the Azure Functions<\/h3>\n
    With our search index and codebase in place, we’re ready to start building our application. The repo follows a pattern for Azure Static Web Apps<\/a> that we’ll be using to build and deploy the application. The functions containing search logic can be found in the api<\/code> folder.<\/p>\n
    One important consideration when building an application is keeping your API keys secure. It’s a best practice to design our application in a way that your API keys aren’t accessible from the client.<\/p>\n
    Azure Functions combined with the Azure SDKs are a simple and effective way to keep our keys out of users’ reach. These functions can also encapsulate any business logic you want to incorporate into the search experience such as security trimming or additional query proccesing.<\/p>\n
    \"Simple<\/p>\n
    Creating a search client<\/h4>\n
    With all that said, we’re ready to get to the code. The api\/search\/index.js<\/code> file contains the Azure Function for search that we’ll walk through below.<\/p>\n
    First, we import the @azure\/search-documents<\/code> library from the SDK as follows:<\/p>\n
    const { SearchClient, AzureKeyCredential } = require(\"@azure\/search-documents\");\n<\/code><\/pre>\n
    Next, we declare a SearchClient<\/code>. This client is declared outside of the main function so that we don’t create a new SearchClient<\/code> every time the Azure Function is called.<\/p>\n
    const indexName = process.env[\"SearchIndexName\"];\nconst apiKey = process.env[\"SearchApiKey\"];\nconst searchServiceName = process.env[\"SearchServiceName\"];\n\n\/\/ Create a SearchClient to send queries\nconst client = new SearchClient(\n    `https:\/\/${searchServiceName}.search.windows.net\/`,\n    indexName,\n    new AzureKeyCredential(apiKey)\n);\n\nmodule.exports = async function (context, req) {\n    \/\/ main function logic\n    \/\/ remainder of code goes here\n}\n<\/code><\/pre>\n
    Note that the API key and other search service parameters are read in using process.env<\/code>. This prevents our API key from being checked into source control and also gives us the flexibility to change these parameters from the Azure portal. For local development, these parameters are pulled from local.settings.json<\/code> which should look like this:<\/p>\n
    {\n  \"IsEncrypted\": false,\n  \"Values\": {\n    \"AzureWebJobsStorage\": \"\",\n    \"FUNCTIONS_WORKER_RUNTIME\": \"node\",\n    \"SearchApiKey\": \"03097125077C18172260E41153975439\",\n    \"SearchServiceName\": \"azs-playground\",\n    \"SearchIndexName\": \"good-books\",\n    \"SearchFacets\": \"authors*,language_code\"\n  }\n}\n<\/code><\/pre>\n
    If you need to limit access to the application or search index, this logic should be handled in the application layer. Fortunately, Azure Static Web Apps makes it easy to add authentication and authorization<\/a> to help secure your data.<\/p>\n
    Defining helper functions<\/h4>\n
    Before the core function logic, we also define two helper function. The first function reads in the facets from proccess.env<\/code> and gets the types of facets. We do this because we need to create filters differently for fields that are arrays. Array fields should be followed by a *<\/code> in the application settings such as authors*<\/code> above:<\/p>\n
    \/\/ parses facets and their types\nconst readFacets = (facetString) => {\n    let facets = facetString.split(\",\");\n    let output = {};\n    facets.forEach(function (f) {\n        if (f.indexOf('*') > -1) {\n            output[f.replace('*', '')] = 'array';\n        } else {\n            output[f] = 'string';\n        }\n    })\n    return output;\n}\n<\/code><\/pre>\n
    The next function will take our filters and convert them into odata syntax that the search service can understand:<\/p>\n
    \/\/ creates filters in odata syntax\nconst createFilterExpression = (filterList, facets) => {\n    let i = 0;\n    let filterExpressions = [];\n\n    while (i < filterList.length) {\n        let field = filterList[i].field;\n        let value = filterList[i].value;\n\n        if (facets[field] === 'array') {\n            filterExpressions.push(`${field}\/any(t: search.in(t, '${value}', ','))`);\n        } else {\n            filterExpressions.push(`${field} eq '${value}'`);\n        }\n        i += 1;\n    }\n\n    return filterExpressions.join(' and ');\n}\n<\/code><\/pre>\n
    Adding the search logic<\/h4>\n
    To start off the core function logic, we read in the parameters from the HTTP request. The facets<\/code> parameter also comes from process.env<\/code> because facets<\/a> are used to create a UI component and are normally consistent across searches:<\/p>\n
    let q = (req.query.q || (req.body && req.body.q));\nconst top = (req.query.top || (req.body && req.body.top));\nconst skip = (req.query.skip || (req.body && req.body.skip));\nconst filters = (req.query.filter || (req.body && req.body.filters));\nconst facets = readFacets(process.env[\"SearchFacets\"]);\n<\/code><\/pre>\n
    For some basic error handling, we next check if the query string, q<\/code>, is undefined or empty, and we set it to *<\/code> if it is. Searching *<\/code> tells the search service to search everything:<\/p>\n
    \/\/ If search term is empty, search everything\nif (!q || q === \"\") {\n    q = \"*\";\n}\n<\/code><\/pre>\n
    Now that the parameters are read in, we use them to create a searchOptions<\/code> variable that adds additional parameters to the search:<\/p>\n
    \/\/ Creating SearchOptions for query\nlet searchOptions = {\n    top: top, \/\/ number of results to return\n    skip: skip, \/\/ number of results to skip; used for paging\n    includeTotalCount: true, \/\/ includes the total number of results\n    facets: Object.keys(facets), \/\/ facets to display on the web page\n    filter: createFilterExpression(filters, facets) \/\/ filter to apply to the query\n};\n<\/code><\/pre>\n
    Next, we send our query to the service to get the search results:<\/p>\n
    \/\/ Sending the search request\nconst searchResults = await client.search(q, searchOptions);\n<\/code><\/pre>\n
    Finally, we loop through the searchResults<\/code> object to get the results and use them to create an HTTP response object that will be returned from our function:<\/p>\n
    \/\/ Getting results for output\nconst output = [];\nfor await (const result of searchResults.results) {\n    output.push(result);\n}\n\n\/\/ Creating the HTTP Response\ncontext.res = {\n    \/\/ status: 200, \/* Defaults to 200 *\/\n    headers: {\n        \"Content-type\": \"application\/json\"\n    },\n    body: {\n        count: searchResults.count,\n        results: output,\n        facets: searchResults.facets\n    }\n};\n<\/code><\/pre>\n
    Handling errors<\/h4>\n
    We’ll also want to do some basic error handling to make the application easier to debug. We do this by adding a simple try catch around our search logic. If our search logic fails, we’ll return a 400 and some details regarding the failure:<\/p>\n
    try {\n    \/\/ search logic from above\n} catch (error) {\n    \/\/ logging the error\n    context.log.error(error);\n\n    \/\/ Creating the HTTP Response\n    context.res = {\n        status: 400,\n        body: {\n            innerStatusCode: error.statusCode || error.code,\n            error: error.details || error.message\n        }\n    };\n}\n<\/code><\/pre>\n
    And with that, you have an Azure Function ready to add search functionality to an application. In the repo, you’ll find similar functions for suggestions and document lookup.<\/p>\n
    Deploying the application with Azure Static Web Apps<\/h3>\n
    With the serverless function complete, we’re ready to connect the search functionality to a front end. In the src<\/code> folder of the repo there is a React template that’s ready to go. Azure Static Web Apps will host both the front end and the back end of our application making the development and deployment of the application a seamless experience.<\/p>\n
    No changes are required to run this with the sample index.<\/p>\n
    To deploy the full application, you first need to create a Static Web App in the Azure portal. Click the button below to create one:<\/p>\n
    \"Deploy<\/a><\/p>\n
    This will walk you through the process of creating the web app and connecting it to your GitHub repo.<\/p>\n
    After connecting to the repo, you’ll be asked to include some build details. Set the Build Presets to React<\/code> and then leave the other default values:<\/p>\n
    \"Azure<\/p>\n
    Once you create the static web app, it will automatically deploy the web app to a URL you can find within the portal.<\/p>\n
    \"Azure<\/p>\n
    The last thing you need to do is select configuration and then edit the application settings to add the credentials from local.settings.json<\/code>. It may take a few minutes for this blade to become available in the portal.<\/p>\n
    \"Azure<\/p>\n
    This post won’t dig into some of the details on building Azure Static Web Apps. However, they’re a valuable tool and if you’re interested in learning more about them, check out the documentation<\/a>.<\/p>\n
    Use your own index<\/h2>\n
    After deploying this sample, I’d encourage you to try it out with your own search index.<\/p>\n
    Up until now, you’ve been working with an existing index, but creating and loading an index with your own data is straightforward. You can create an index in the Azure portal<\/a>, use the REST APIs<\/a>, or use any of the Azure SDKs such as the new Azure SDK for Javascript\/TypeScript<\/a> that we used in this blob post. Please see the Azure Cognitive Search documentation<\/a> for more information on how to get started.<\/p>\n
    There are two main changes you’d need to make to use your own index:<\/p>\n
    1. Edit application settings in the portal<\/h3>\n
    Navigate to the Azure portal -> find your Azure Static Web App -> select configuration -> edit the application settings.<\/p>\n
    2. Update Result and Detail components<\/h3>\n
    Much of the UI won’t require customization, however, if you integrate a new index with this template, you’ll likely need to update the Results<\/code> component and the Details<\/code> component to reflect the fields in your index.<\/p>\n
    To give an example, the following code renders the results on the search page in src\/components\/Results\/Result\/Result.js<\/code>. The properties id<\/code>, image_url<\/code>, and original_title<\/code> of props.document<\/code> all correspond to fields in the search index and should be updated to reflect the fields in your own search index:<\/p>\n
    <div className=\"card result\">\n    <a href={`\/details\/${props.document.id}`}>\n        <img className=\"card-img-top\" src={props.document.image_url} alt=\"book cover\"><\/img>\n        <div className=\"card-body\">\n            <h6 className=\"title-style\">{props.document.original_title}<\/h6>\n        <\/div>\n    <\/a>\n<\/div>\n<\/code><\/pre>\n
    Check out the docs<\/code> folder of the repo for more detail on customizing the web app.<\/p>\n
    <\/p>\n
    Azure SDK Releases<\/a><\/div><\/p>\n
    Azure SDK Blog Contributions<\/h2>\n
    Thank you for reading this Azure SDK blog post! We hope that you learned something new and welcome you to share this post. We are open to Azure SDK blog contributions. Please contact us at azsdkblog@microsoft.com<\/a> with your topic and we’ll get you setup as a guest blogger.<\/p>\n
    Azure SDK Links<\/h2>\n