# Introduction Source: https://doc.lucidworks.com/docs/lw-platform/index Discover how to deploy, customize, and scale Lucidworks products for AI-powered search and insights across B2B, B2C, knowledge management, customer support, and more. > **[Contact Lucidworks](https://lucidworks.com/demo/?utm_source=docs\&utm_medium=referral\&utm_campaign=docs_cta)** > > Reach out with your current search challenges and what you hope to achieve with a search and discovery solution. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Discover Get started quickly with product-specific guides and tools for building intelligent search, analytics, and AI applications. > **[Lucidworks AI](/docs/lw-platform/lw-ai/overview)** > > Advanced AI-powered data discovery and search > **[Neural Hybrid Search](/docs/lw-platform/lw-ai/quickstart-lucidworks-ai-nhs-rag)** > > Combine lexical precision with semantic understanding for more relevant results > **[Core Settings](/docs/lw-platform/lw-core/overview)** > > Build fast, intuitive, and configurable search experiences > **[Agent Studio](/docs/lw-platform/lw-agent-studio/overview)** > > Prototype and deploy enterprise-grade AI agents > **[Commerce Studio](/docs/lw-platform/lw-cs/overview)** > > Optimize search results and improve product discovery > **[Analytics Studio](/docs/lw-platform/lw-analytics/overview)** > > Transform data into actionable intelligence > **[Signals Beacon](/docs/lw-platform/lw-analytics/signals/overview)** > > Low-code signal capture for advanced analytics # Latest changes Source: https://doc.lucidworks.com/docs/lw-platform/latest-changes Lucidworks products are constantly evolving to deliver new features, improvements, and fixes. This page highlights the latest changes to help you stay current with product updates and enhancements. [localhost link]: http://localhost:3000/docs/lw-platform/latest-changes [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/latest-changes **2026-08-28** # Search Results Layout Settings The Commerce Studio Settings feature now provides the option to display search results in a list, or in the current default grid pattern. The **Layout** section lets you select to display search results in a vertical list or a grid pattern. ![List layout setting](https://mintcdn.com/lucidworks/NXdmPj01VTcfSoKs/assets/images/lw-platform/commerce-studio/lw-cs-settings-layout.png?fit=max\&auto=format\&n=NXdmPj01VTcfSoKs\&q=85\&s=f9fc0259999200dcb39060eaae429645) For example, if you select the **List** option, the search results display in a vertical list on the Editor screen. ![List layout search results](https://mintcdn.com/lucidworks/NXdmPj01VTcfSoKs/assets/images/lw-platform/commerce-studio/lw-cs-editor-preview-layout-list.png?fit=max\&auto=format\&n=NXdmPj01VTcfSoKs\&q=85\&s=924df51496ef8f9ebf6a724f5f7219d4) For more information, see [Commerce Studio Settings Layout](/docs/lw-platform/lw-cs/cstudio-settings#layout). **2026-07-31** # Configure the Vector Similarity Threshold and Vector Result Count of Neural Hybrid Search The Lucidworks Platform Core Settings Relevance option has been enhanced with two new fields: * **Vector Similarity Threshold** lets you set the minimum of how closely a document must match your query's meaning to be included in results. Enter a decimal value between `0` and `1`. A higher minimum value returns only results that strongly match the query's meaning. A lower minimum value returns more results because results do not have to match the query's meaning as closely. * **Vector Result Count** specifies how many candidate results the vector (semantic) search retrieves before the results are merged and re-ranked with the lexical results. Enter an integer between `0` and `2000`. A higher value assesses more semantic candidate results, which improves relevant results. A lower value assesses fewer semantic candidate results, which may decrease relevant results. ![NHS settings options](https://mintcdn.com/lucidworks/FtDps0vG_MOhPC6g/assets/images/lw-platform/sites/sites-nhs.png?fit=max\&auto=format\&n=FtDps0vG_MOhPC6g\&q=85\&s=b916b7baf20218ecb6fbb21b482d972a) For more information, see [Relevance](/docs/lw-platform/lw-core/sites-relevance) and [NHS Quickstart](/docs/lw-platform/lw-core/quickstart). **2026-07-31** # Exclude rules from Commerce Studio Editor results preview The Execute section of the Commerce Studio Editor screen now gives you the option to include or exclude a rule from the query being previewed. This lets you test to see the search results if the rule is removed from a query without actually deleting the rule. ![Rule state and preview setting](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-editor-view-rules.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=c64a0fb11723c425fa7ddb46736ce5a2) Click the **Preview** toggle `on` to execute that rule in the query, or click **Preview** `off` to exclude it from the query. The query results display based on the rules included in the query. > [!NOTE] > > Your live site is *never* affected by setting the **Preview** toggle to `off`. **2026-07-10** # Customize the UI Studio composition canvas The Customize Section option of UI Studio lets you set a background color and size for a composition that matches your organization's branding or for a specific search experience. When you access UI Studio, click **Builder**, and select the composition to customize, the Composition Editor screen displays. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-new-editor.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=b278cd085415046cc47371f1b3cb532d) Composition Editor screen Click the main canvas and then click the gear icon to open the **Customize Section** panel. Set a background color for the composition. You can also or adjust the section dimensions. These settings can be refined at any time. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-canvas-properties.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=aeebfe42c44115426cbc5a184e88c181) Customize canvas properties **2026-07-06** # Add a UI Studio composition The Create New UI feature of UI Studio lets you [add a new composition](/docs/lw-platform/lw-ui-studio/compositions#add-a-composition) to build a new search experience page for your users. This UI option is a user-friendly method to add a search page customized to your organization and doesn't require engineering resources. When you access UI Studio and click **Builder**, the **Create New UI** option lets you name the new composition. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/compositions-main.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=f4dbb51ff11910f83cf8169f295b59b1) The Compositions screen, where you create, manage, and publish your UI Studio compositions. Add the name and description and click **Create**. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-add-new.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=edd06b9be4a134296698bee6a2873697) Add a new composition. The new composition is listed on the Compositions screen that lets you [add and customize components](/docs/lw-platform/lw-ui-studio/compositions#build-a-composition) such as a search bar, facets, and a results section. **2026-06-30** # Unified Platform Login If you're using Lucidworks Search, you can now access Fusion instances and Grafana dashboards directly from Lucidworks Platform using single sign-on (SSO) authentication. Unified Platform Login eliminates the need to log in separately to each system and provides a seamless, secure authentication experience powered by Okta. When you click the **Managed** button from Lucidworks Platform's Indexes tab, you're authenticated automatically and redirected to your Fusion instance without entering additional credentials. The same SSO experience extends to Grafana dashboards accessed with the **View Metrics** option. ![Managed button on a Fusion instances card](https://mintcdn.com/lucidworks/sM1ZkypaV6Y04faJ/assets/images/lw-platform/indexes-managed-cropped.png?fit=max\&auto=format\&n=sM1ZkypaV6Y04faJ\&q=85\&s=cf620eae6d1d356a3e75d14fd791904b) ![View Metrics item under the three dots on a Fusion instances card](https://mintcdn.com/lucidworks/sM1ZkypaV6Y04faJ/assets/images/lw-platform/indexes-viewmetrics-cropped.png?fit=max\&auto=format\&n=sM1ZkypaV6Y04faJ\&q=85\&s=48a12db8060668c34193fa2f6b7649d7) All authentication infrastructure is managed by Lucidworks—no manual security realm, OIDC, or group mapping configuration required. > [!NOTE] > > Unified Platform Login works with Lucidworks Search. > It does not apply to self-hosted Fusion. If you need elevated access to perform administrative tasks in an instance of Lucidworks Search, request role elevation from Lucidworks Support or your Customer Success Manager. After the role is granted, log in again with Lucidworks Platform to activate your new permissions. See [Fusion instances](/docs/lw-platform/lw-platform/indexes#fusion-instances) for complete details. **2026-06-05** # Draft edits for all rule types in Commerce Studio Commerce Studio now supports draft edits for every rule type, so merchandisers can update a published rule without taking it offline. When you open a published rule for editing, the published version stays active on your site and your changes are captured as a draft. You can then **Publish** the changes immediately, **Save as Draft** to preview the impact in the Editor, or **Cancel** to discard the edits. ![Draft edit for a pin rule in Commerce Studio Editor](https://mintcdn.com/lucidworks/QFIIrygn-VpJZuMC/assets/images/lw-platform/commerce-studio/draft-edit-rule-editor.png?fit=max\&auto=format\&n=QFIIrygn-VpJZuMC\&q=85\&s=4274a273ef39302c143a9c9a7fc96893) Draft edit for a pin rule in Commerce Studio Editor The live rule keeps serving traffic while edits are staged, so you can refine merchandising logic before it reaches users. On the Rules screen, a published rule with a draft appears as two rows so it is always clear which version is live and which has unpublished changes. Bulk actions, filters, and row-level actions all reflect draft state. ![Draft edit for a pin rule in Commerce Studio Rules screen](https://mintcdn.com/lucidworks/QFIIrygn-VpJZuMC/assets/images/lw-platform/commerce-studio/draft-edit-rule.png?fit=max\&auto=format\&n=QFIIrygn-VpJZuMC\&q=85\&s=708c14471833bb7c866c5a59493d7b38) Draft edit for a pin rule in Commerce Studio Rules screen For more information, see [Manage rules](/docs/lw-platform/lw-cs/cstudio-rules#manage-rules). **2026-06-05** # Part Number detection The Part number detection feature is a specialized query processing feature that automatically detects part number patterns in search queries, and then optimizes search behavior to balance lexical precision with semantic understanding. In part number searches, lexical matching is the more dominant function and highly accurate, lexically focused results are returned. Semantic matching is minimized for part number searches, but is not impacted for general queries. Part number detection employs a Fusion LWAI Prediction stage you create. You must [configure the stage to use the Part Number Classification custom-trained model](/docs/lw-platform/lw-ai/lw-ai-custom-embedding-model-training/create-and-deploy-custom-models#create-a-new-model). To further optimize part number searches, you can complete the following actions: * Configure any other Fusion stage with conditional statements that return the boolean from part number detection (if applicable to your business). * Tune the Neural Hybrid Query stage to give more weight to lexical search. ## Use cases * Business-to-consumer organizations that offer products identified with model or part numbers can use part number detection to accurately return results to help users select the correct item, which increases customer satisfaction and reduces product returns. * Business-to-business organizations that rely heavily on part numbers, SKUs, or product codes, use part number detection to identify the products they distribute. The correct selection of products is essential to their customers, and enable targeted purchases, encourage repeat orders, and build the long-term customer relationships that help B2B organizations thrive. * Knowledge management searches use part number detection to return results from your company's knowledge bases, technical documents, inventory catalogs, and other documents. Easy and fast access to this information increases productivity and access to accurate, up-to-date information. ## Examples When the stages are configured, the part number detection feature can be used in Fusion or in Lucidworks AI. The following example reflects when a part number is detected (`true`): ![Part number detected](https://mintcdn.com/lucidworks/SCoV0-xa5fgs7bNI/assets/images/lw-platform/lw-ai/part-number-detection-true.png?fit=max\&auto=format\&n=SCoV0-xa5fgs7bNI\&q=85\&s=dc5f8918a92f6cb43c3dcd082bf757a2) Part number detected The following example reflects when a part number is not detected (`false`): ![Part number not detected](https://mintcdn.com/lucidworks/SCoV0-xa5fgs7bNI/assets/images/lw-platform/lw-ai/part-number-detection-false.png?fit=max\&auto=format\&n=SCoV0-xa5fgs7bNI\&q=85\&s=baba16bea245e9715c5acca13e66284a) Part number not detected For more information, see the following topics: * [Fusion Part Number Detection in Neural Hybrid Search](/docs/5/fusion/hybrid-search/part-number-detection-in-nhs) * [Lucidworks Search Part Number Detection in Neural Hybrid Search](/docs/lucidworks-search/11-vector-search/part-number-detection-in-nhs) * [Lucidworks AI Prediction API Part Number Detection use case](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-prediction-api/part-number-detection-use-case) * [Lucidworks AI Prediction API Part Number Detection API specification](/api-reference/get-predictions/part-number-detection-use-case) **2026-06-03** # Introducing UI Studio Lucidworks UI Studio is a no-code visual experience builder for creating and launching enterprise-grade, AI-powered search applications on the Lucidworks Platform. Teams can design branded, multi-page search experiences using drag-and-drop components, live previews, and configurable search integrations without relying on engineering resources. ![Build a search UI in minutes](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/component-configuration.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=c1a9314e583453f26a7d941ceffb9d22) Build a search UI in minutes Unlike traditional search UI frameworks and developer SDKs that require frontend development expertise, UI Studio empowers search administrators, digital teams, and business users to visually create and manage search experiences independently. Organizations can rapidly launch search interfaces that are accurate, scalable, branded, and production-ready. > **[Search Bar](/docs/lw-platform/lw-ui-studio/components/search-bar)** > > Accept user queries and trigger search across your datastore. > **[Results](/docs/lw-platform/lw-ui-studio/components/results)** > > Display search results in List, Grid, or Table views with sorting and pagination. > **[Facets](/docs/lw-platform/lw-ui-studio/components/facets)** > > Let users narrow results by filtering on field values. > **[Button](/docs/lw-platform/lw-ui-studio/components/button)** > > Add navigation, export, or action buttons to your pages. > **[Image](/docs/lw-platform/lw-ui-studio/components/image)** > > Display images with optional links, borders, and fallback support. > **[Text](/docs/lw-platform/lw-ui-studio/components/text)** > > Add static or dynamic text content with rich styling options. UI Studio supports both SaaS and self-hosted Fusion deployments, and integrates natively with Lucidworks Search, AI-powered relevance, typeahead, version control, and secure publishing. ## Key capabilities * Drag-and-drop creation of branded, multi-page search applications * Built-in integration with Lucidworks Search, AI-powered relevance, and typeahead * Live preview with real production data during configuration * Visual theming and branding controls for consistent enterprise design * Secure publishing to Lucidworks-managed hosting in minutes * Version control and rollback for safe iteration * Enterprise authentication support including SSO-secured experiences ## Use cases > **B2B commerce** > > B2B buyers work with large, complex product catalogs and require precise access to technical specifications, parts, and contract terms. UI Studio enables B2B organizations to rapidly deploy branded search experiences without dedicating frontend engineering resources. Search administrators can configure facets, sorting, and relevance tuning to match complex procurement workflows and publish updates independently. This reduces implementation friction, shortens time-to-value, and allows engineering teams to focus on higher-priority initiatives. > **B2C commerce** > > B2C customers expect fast, intuitive, and visually consistent search experiences. UI Studio allows ecommerce and digital teams to create branded product discovery experiences with configurable search bars, facets, typeahead, and results pages. Teams can preview changes against live data, iterate quickly without code, and publish confidently with built-in version control. This improves product findability, reduces cart abandonment, and accelerates time-to-launch for new storefronts and campaigns. > **Knowledge management** > > Enterprise knowledge management programs often span multiple portals: employee search, technical documentation, supplier resources, and customer support. UI Studio enables organizations to launch and maintain each of these experiences independently, without parallel frontend development projects. Search administrators can manage layouts, components, and pages through a visual interface while automatically capturing behavioral signals to improve relevance over time. ## Dive in > **[UI Studio](/docs/lw-platform/lw-ui-studio/overview)** > > Explore the UI Studio documentation to learn how to build, customize, and publish enterprise-grade search experiences without writing code. > **[Request a UI Studio demo](https://lucidworks.com/demo/?utm_source=docs\&utm_medium=referral\&utm_campaign=docs_cta)** > > See UI Studio in action and learn how your team can launch enterprise search experiences faster without frontend development. **2026-06-01** # Bulk operations API for Commerce Studio The Rules and Rewrites API for Commerce Studio now supports bulk operations, so you can publish, unpublish, edit, delete, or migrate multiple rules in a single request instead of calling the API once per rule. ![Create bulk operations to act on multiple Commerce Studio rules in a single request.](https://mintcdn.com/lucidworks/NVeDO2OLvLD4UfJD/assets/images/diagrams/rules-rewrites-bulk-api.png?fit=max\&auto=format\&n=NVeDO2OLvLD4UfJD\&q=85\&s=0749a433b1f3cd652b79b8bf05b1f00e) Bulk operations run asynchronously. You submit a request that targets rules by ID, external ID, or a filter, then poll the operation status until it completes. These capabilities support enterprise use cases where per-rule API calls do not scale, such as: * Publishing or unpublishing large sets of rules for a seasonal campaign * Applying the same edit across every rule that shares a tag * Deleting obsolete rules in a single batch * Migrating a rule set to another Commerce Studio instance Bulk operations require an authentication token with the `commercestudio.bulkoperations` scope. See [Bulk operations](/docs/lw-platform/lw-cs/cs-rules-rewrites-api#bulk-operations) for usage instructions and example requests. For complete endpoint specifications, see the [Bulk Operations API reference](/api-reference/bulk-operations/list-bulk-operations). **2026-05-29** # Product Impressions Metrics Product impressions measure the number of times a product displays in search results in response to user queries. The product is counted each time it displays, even if users do not interact further with the product. You can use impressions metrics to help your organization perform these important functions: * Track impression changes after merchandising updates or catalog modifications to monitor trends over time * Analyze impressions for different search categories or product types and segment by query type * Identify high-impression products that may need pricing or promotion adjustments * Include impression analysis in regular merchandising reviews to maintain optimal product exposure You can configure impressions metrics in [Analytics Studio metrics](/docs/lw-platform/lw-analytics/analytics-screen#param-top-performing-products) for top performing products. ![Top Performing Products dashboard with Impressions per product](https://mintcdn.com/lucidworks/vMCWPL7hzLnycFmk/assets/images/lw-platform/analytics/analytics-top-performing-products-impressions.png?fit=max\&auto=format\&n=vMCWPL7hzLnycFmk\&q=85\&s=43b8b4a4fa30c87a54ae42a9a791f0f0) You can also configure [Commerce Studio inline analytics](/docs/lw-platform/lw-cs/cstudio-settings#inline-analytics) to display impressions on product cards. ![Commerce Studio Editor product card with metrics](https://mintcdn.com/lucidworks/oD_48DY4nfwwUSpE/assets/images/lw-platform/commerce-studio/lw-cs-product-card-impression-metrics.png?fit=max\&auto=format\&n=oD_48DY4nfwwUSpE\&q=85\&s=c583de59aa067e972326c36be2fd9f9e) For more information about how to use impressions metrics to optimize search experiences and product visibility, see [Impressions metrics](/docs/lw-platform/lw-cs/cstudio-editor#impressions-metrics). **2026-05-29** # AND logic for attribute rules in Commerce Studio Commerce Studio now supports **AND logic** across attribute field value conditions in [Boost by Attribute](/docs/lw-platform/lw-cs/cstudio-rules#boost), [Bury by Attribute](/docs/lw-platform/lw-cs/cstudio-rules#bury), and [Block by Attribute](/docs/lw-platform/lw-cs/cstudio-rules#block) rules, enabling precise targeting of specific product combinations. Previously, attribute rules could only use OR logic between different attributes. For example, `Color = Black OR Type = Pants` would affect all black items and all pants, even if the items didn't meet both conditions. Now you can create rules that require multiple attributes to match simultaneously in one rule: * `(Color: Black, Red) AND (Type: Shirt)` — Boost only shirts that are black or red * `(Brand: Nike) AND (Gender: Women) AND (Category: Running)` — Boost women's Nike running shoes * `(Clearance: True) AND (Available: 0)` — Bury out-of-stock clearance items This enhancement enables merchandising scenarios such as: * Boosting seasonal product combinations like winter coats or summer dresses across multiple brands or colors * Burying clearance items that are out of stock to reduce customer frustration * Promoting new arrivals within specific high-margin categories * Burying products that do not meet a product speficiation in the query Existing attribute rules continue to use OR logic between attributes, ensuring backward compatibility for older rules. For more information, see [Commerce Studio Rules](/docs/lw-platform/lw-cs/cstudio-rules). > [!NOTE] > > This feature requires Fusion or Lucidworks Search 5.17.1 or later. **2026-05-29** # Numeric field operators for Commerce Studio rules Commerce Studio now supports numeric comparison operators for field value conditions in [Boost by Attribute](/docs/lw-platform/lw-cs/cstudio-rules#boost), [Bury by Attribute](/docs/lw-platform/lw-cs/cstudio-rules#bury), and [Block by Attribute](/docs/lw-platform/lw-cs/cstudio-rules#block) rules. The Commerce Studio UI now provides operators for creating attribute-based rules with numerical field comparisons. Previously, configuring numeric conditions required writing Solr queries directly. This enhancement enables merchandising scenarios such as: * Boosting products with inventory levels that exceed a threshold * Burying items with low customer ratings * Blocking products priced outside acceptable ranges * Promoting items within specific price brackets during sales See [Field value operators](/docs/lw-platform/lw-cs/cstudio-rules#field-value-operators) for complete details about configuring numeric comparison conditions. > [!NOTE] > > This feature requires Fusion or Lucidworks Search 5.17.1 or later. **2026-05-22** # Platform Signals integration The Boost with Signals query pipeline stage in Fusion and Lucidworks Search now supports Platform Signals as a data source, enabling you to use the Signals Beacon or Platform Signals API to feed behavioral data directly into search relevance boosting. Previously, only native signals were supported, requiring more cumbersome parallel signal infrastructure to influence search ranking. ![Signals Beacon sending signas to Fusion's \_signals\_aggr collection](https://mintcdn.com/lucidworks/qYqgr7QIknt_0r9M/assets/images/diagrams/signals-beacon-fusion.png?fit=max\&auto=format\&n=qYqgr7QIknt_0r9M\&q=85\&s=8f2c598802e7d3981116a21db33bb0c0) This integration eliminates that duplication. Customers already capturing user behavior through Platform Signals can now use that same data to drive query boosting, turning behavioral analytics into active search optimization without additional infrastructure. **Fusion**: See [Platform Signals](/docs/5/fusion/getting-data-in/platform-signals/overview) for configuration details. **Lucidworks Search**: See [Platform Signals](/docs/lucidworks-search/04-move-data-in/platform-signals/overview). **2026-05-20** # Form Builder for rules Commerce Studio now includes a Form Builder for creating rules directly on the Rules screen, without opening the Editor. When you know exactly what rule you want to create and do not need to see search results in context, the Form Builder is faster than the Visual Builder workflow. ![Form Builder](https://mintcdn.com/lucidworks/v8Oy1RZSpfLxwDN_/assets/images/lw-platform/commerce-studio/manual-builder.png?fit=max\&auto=format\&n=v8Oy1RZSpfLxwDN_\&q=85\&s=189b3f0ac3af40770dfd20f5b075fdd9) Form Builder in Commerce Studio Use the Form Builder when you want to define conditions and actions without a live preview. See [Form Builder](/docs/lw-platform/lw-cs/cstudio-rules#manual-builder) in the Rules documentation for configuration details. **2026-05-06** # Conversational Q\&A and FAQ agents Two new Agent Studio agents are now available. Both the Conversational Q\&A agent and the Conversational Q\&A FAQ agent are AI-powered and live on your organization's product detail pages. Customers can ask natural-language questions about a product, and the agent responds with accurate, real-time answers grounded in that product's own documentation, such as datasheets, manuals, specifications, and other supporting PDF technical content. ![Create a custom agent](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-qna-name-select-agent.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=eebd5386b880170223fa66a5106d58c7) These agents save your customers time-consuming and difficult research to obtain the information they need to help make a purchasing decision. They also enhance customer satisfaction, increase the potential for conversions, and improve the relationship between your customers and your organization. In addition, the Conversational Q\&A FAQ agent provides frequently asked questions based on questions users may ask about the product or information. This gives the user more information about their query, which helps minimize customer support calls and product returns. [Conversational Q\&A FAQ agent example](https://app.supademo.com/embed/cmords7yg44fdw9dophsneqci?embed_v=2\&utm_source=embed) You can quickly and easily create multiple agents that enhance your ability to provide information 24/7 to customers and internal purposes. For example, you may have one agent for customers about product information, and another for employees to get information about organization policies. **2026-04-30** # Core Settings for multiple query profiles [Core Settings](/docs/lw-platform/lw-core/overview) now supports managing multiple query profiles within a single site, enabling you to configure and maintain distinct search experiences for different use cases. When your site has multiple query profiles, a query profile selector appears at the top of the Core Settings interface. You can switch between profiles to configure each search experience independently without affecting other profiles. ![Query profiles dropdown on the Core Settings > Relevance page](https://mintcdn.com/lucidworks/FtDps0vG_MOhPC6g/assets/images/lw-platform/core-settings/core-settings-relevance-query-profiles.png?fit=max\&auto=format\&n=FtDps0vG_MOhPC6g\&q=85\&s=665543fc24f59880ff98a15f1b2ebbfa) This capability supports enterprise deployments that require any of the following: * Separate search configurations for different websites or applications * Different ranking strategies for various content types * Dedicated search behaviors for internal versus public users * Distinct search experiences for multiple audiences or regions > [!NOTE] > > The query profile selector only appears when your site has multiple query profiles configured. > Sites with a single query profile continue to work exactly as before with no interface changes. See [Query profiles](/docs/lw-platform/lw-core/overview#query-profiles) for complete details about managing multiple search configurations. **2026-04-30** # Rules and Rewrites API Commerce Studio now provides a public-facing Rules and Rewrites API that enables programmatic management of merchandising rules and query rewrites. This API supports enterprise automation workflows, enabling you to create, update, and synchronize rules across multiple environments through CI/CD pipelines, internal tools, and custom integrations. ![Create and update rules and rewrites programmatically with the Rules and Rewrites API for Commerce Studio.](https://mintcdn.com/lucidworks/NFEfKXP0Efo-eBaS/assets/images/diagrams/rules-rewrites-api.png?fit=max\&auto=format\&n=NFEfKXP0Efo-eBaS\&q=85\&s=46e388a5910f7ac0db05d40946ed0d5b) The API introduces external ID support, allowing you to assign your own identifiers to rules and rewrites for consistent cross-environment synchronization. For example, you can create a rule with an external ID like `summer-promo-2026` in development, then deploy the same rule to QA and production using that identifier to ensure changes propagate correctly across all environments. These capabilities address enterprise use cases where manual UI-based rule management does not scale: * **Automated deployments**: Integrate rule management into CI/CD workflows for consistent, repeatable deployments. * **Cross-environment synchronization**: Maintain identical rule sets across development, QA, and production. * **Internal system integration**: Connect Commerce Studio to merchandising platforms, promotion systems, or custom tooling. * **Large-scale rule management**: Efficiently manage rule sets that are impractical to maintain manually. Rate limiting protects platform stability, and the API follows RESTful conventions with support for create, read, update, and delete operations. See [Rules and Rewrites API](/docs/lw-platform/lw-cs/cs-rules-rewrites-api) for authentication details, key concepts, and usage instructions. For complete endpoint specifications, see the [Rules and Rewrites API reference](/api-reference/rule-management/list-rules). **2026-04-30** # Average Click Position Commerce Studio and Analytics Studio now display the average ranking position of products in the search results when the customer clicks those products. A lower average click position is better, because that means customers are finding the product near the top of the results, which provides the following benefits: * Increased customer satisfaction with the search experience * Enhanced conversion rates * Minimized cart abandonment and loss of sales to competitors If the product position needs to display higher, your ecommerce team can modify or create rules to increase that product's visibility. This metric helps ecommerce teams validate merchandising rules, optimize product visibility, and measure the impact of search configuration changes on customer engagement and conversion rates. ## Average click position graph in Commerce Studio The Ranking Insights panel in Commerce Studio displays average click position of the query specified in the Conditions Manager section of the Editor screen. The metric is calculated by dividing the sum of all clicked positions by the total number of clicks for the current query and time period selected in the Editor screen. ![Average Click Position](https://mintcdn.com/lucidworks/yabQiFvt3JED8B7C/assets/images/lw-platform/commerce-studio/lw-cs-ranking-insights4.png?fit=max\&auto=format\&n=yabQiFvt3JED8B7C\&q=85\&s=dde6f67eca93be8662952a255d265b8a) ## Average click position graph in Analytics Studio The Analytics Studio Signals Analytics screen displays an average click position graph that measures the average ranking position for all products for the designated time period. The metric is calculated by dividing the sum of all clicked positions by the total number of clicks for the time period displayed. ![screen name](https://mintcdn.com/lucidworks/yabQiFvt3JED8B7C/assets/images/lw-platform/analytics/average-click-position.png?fit=max\&auto=format\&n=yabQiFvt3JED8B7C\&q=85\&s=7a02efeb5334448e2e21d309c6692214) See [Types of metrics](/docs/lw-platform/lw-analytics/analytics-screen#types-of-metrics) for more information. **2026-04-15** # Starts With and Ends With query matching Commerce Studio now supports **Starts With** and **Ends With** query matching methods, giving you more precise control over when rules trigger. These new matching options complement the existing **Is**, **Contains**, and **Contains Phrase** methods by enabling prefix- and suffix-based targeting strategies. These enhancements enable the following capabilities: * Target branded searches when queries begin with specific brand names. * Apply location-specific logic when queries end with "near me". * Trigger help content when queries end with "manual," "pdf," or "replacement". * Reduce rule sprawl by creating precise, structured query patterns instead of multiple broader rules. Both matching methods support multi-word phrases with word order respect, ensuring predictable behavior. For example, a rule set to "\[starts with] winter jackets" triggers for "winter jackets sale" but not "jackets winter sale." ![Starts with and ends with query matching](https://mintcdn.com/lucidworks/ifia9GAyjG34mjm5/assets/images/lw-platform/commerce-studio/starts-with-ends-with.png?fit=max\&auto=format\&n=ifia9GAyjG34mjm5\&q=85\&s=4ad8025504fedd02a39e066c5b0bf028) This update improves merchandising precision without increasing technical complexity, maintaining the same familiar workflow you use today. See [Rules](/docs/lw-platform/lw-cs/cstudio-rules#conditions) for complete details about configuring query matching methods, including examples for e-commerce and knowledge management use cases. > [!NOTE] > > This feature requires Fusion or Lucidworks Search 5.17.0 or later. **2026-04-14** # Generative AI using Lucidworks-managed keys Lucidworks now offers the option to execute generative AI models using Lucidworks-managed API keys, which eliminates the need for your organization to manage third-party credentials across multiple large language model (LLM) providers such as OpenAI, Anthropic, Google, and Azure. This business option delivers significant operational and strategic advantages in a simplified deployment that eliminates complex third-party integrations and allows your teams to focus on business goals rather than credential management. Your organization benefits from reduced costs with predictable, fixed pricing instead of unpredictable per-token charges across multiple vendors. This lowers administrative overhead for managing vendor relationships and billing accounts. This Lucidworks-managed service handles the complete lifecycle of Gen-AI model execution through the Lucidworks AI Gateway for Gen-AI use cases in the Prediction API and Async Prediction API. Your organization will configure dedicated Fusion pipelines using LWAI Prediction index and query stages with `Use Case` and `Model` values provided by Lucidworks, while Lucidworks manages the underlying infrastructure, API key lifecycle, and model routing. ![LWAI Prediction index stage](https://mintcdn.com/lucidworks/kFGC-3RuCRBkNmSp/assets/images/lw-platform/lw-ai/lw-ai-gen-ai-lw-generated-keys.png?fit=max\&auto=format\&n=kFGC-3RuCRBkNmSp\&q=85\&s=45da0c87f5dd50528f019f9b0d1c2bb3) Contact Lucidworks to find out about feature availability per your Lucidworks Platform contract. **2026-03-30** # Advanced grouping Commerce Studio now supports advanced grouping, a conditional, rule-based approach to product variant grouping that gives you dynamic control over how products are grouped in search results. Unlike standard variants that apply uniformly across all products and queries, advanced grouping uses rules to trigger different grouping parameters based on conditions such as queries, categories, or other criteria. For example, you can group products by color for fashion queries while grouping by product ID for electronics queries. This dynamic capability enables you to create context-aware grouping strategies that adapt to different search scenarios, improving product discovery and the customer experience. See [Advanced grouping](/docs/lw-platform/lw-cs/cstudio-rules#advanced-grouping) in the Rules documentation for complete configuration details. **2026-03-17** # Category management for Commerce Studio Because category-level optimization plays a critical role in guiding product discovery and driving conversion, Commerce Studio now includes a dedicated Category Management workspace that lets merchandisers easily curate and optimize category pages without complex Fusion configuration. You can select categories using both readable names and IDs, apply category-level rules and conditions, preview changes before publishing, and measure performance with integrated analytics. This streamlined experience empowers your merchandising team to manage browse experiences with the same speed, control, and insight available for search—reducing reliance on engineering and accelerating time to impact. You can configure the category field on the [Settings](/docs/lw-platform/lw-cs/cstudio-settings) screen, then [use category conditions](/docs/lw-platform/lw-cs/cstudio-editor#use-category-conditions) in the Editor to access the available categories and optimize the results for each one: ![Category management in the Commerce Studio Editor's Conditions Manager](https://mintcdn.com/lucidworks/2b9yyNKfDTYuhcWc/assets/images/lw-platform/commerce-studio/lw-cs-editor-category.png?fit=max\&auto=format\&n=2b9yyNKfDTYuhcWc\&q=85\&s=769b94d3eb66051244ed52ac1f55bf28) Contact Lucidworks to find out about feature availability per your Lucidworks Platform contract. **2026-02-18** # Typeahead The new Typeahead feature is now available in Lucidworks Platform Core Settings to help customers find results faster with real-time query suggestions as they type. The feature supports Included and Excluded suggestion lists to control which typeahead suggestions appear as customers type. Users can manually add terms to both lists while the Platform automatically populates the table with the most popular terms from a linked [Signals Store](/docs/lw-platform/lw-analytics/signals/signals-store). As your customer enters text into the search box on your site, the Typeahead feature uses the Included suggestions list to predict possible customer queries and displays suggestions in real time. When the customer clicks on the suggestion, results for the selected term display. This function helps customers find relevant results faster by predicting what they are trying to search. See [Typeahead](/docs/lw-platform/lw-core/sites-typeahead) for information to enter and manage suggestions. To retrieve a full or partial list of suggestions for your organization, see [Typeahead Service API](/docs/lw-platform/lw-core/typeahead-api). **2026-02-18** # AI Ranking Insights AI Ranking Insights is a new Commerce Studio feature that displays a clear, business-friendly explanation about why a product or content is ranked in a given position. When you click a search result, and then click **AI Ranking Insights**, this feature uses a large language model (LLM) to interpret primary ranking drivers, such as text relevance, rules, boosts, rewrites, and AI-driven signals like Neural Hybrid Search (NHS), in Fusion's debug response. Specifically, AI Ranking Insights identifies key relevancy influencers including merchandising rules, matching fields, and matching logic, and then returns the reasoning in a readable format so merchandisers and search managers can quickly identify the key factors influencing a search result's relevancy. For example, if you click on a bathroom faucet handle pinned as first in a search for "bathroom faucet", the response is: "Bathroom Faucet Handle ranks #1 out of 12550 total results because of a pin rule that explicitly places this specific product at the top of the results for the query bathroom faucets. This merchandising rule overrides the organic search ranking to ensure the product appears in the first position." Using this information, the merchandiser or search manager can modify the factors of this and other search results, if needed, to rank other results higher than the bathroom faucet handle. See [AI Ranking Insights](/docs/lw-platform/lw-cs/cs-ai-ranking-insights) for complete details and instructions to use this feature. **2026-01-20** # Image Data Enrichment The new Image Data Enrichment feature in Lucidworks AI automatically enhances product catalogs with richer attributes by analyzing each item's images and text fields to infer relevant details. By enriching your catalog's categories, keywords, and synonyms, you make it easier for customers to find what they're looking for—driving higher conversions and reducing search abandonment. This feature is especially powerful when your product catalog is too large for manually adding details to every item. See [Image Data Enrichment](/docs/lw-platform/lw-ai/data-enrichment) for complete details and instructions for enabling the feature. You can use this feature with or without Fusion. **2025-12-12** # Streaming responses for the LWAI Prediction API The LWAI Prediction API now supports streaming responses, enabling applications to receive model output as it is generated. This improves responsiveness for interactive workloads such as chat experiences and real-time content generation. Clients can enable streaming by adding the `Accept: text/event-stream` header to synchronous prediction requests, which returns model output as a sequence of Server-Sent Events (SSE). Streaming is available only when calling the LWAI Prediction API directly as Fusion does not yet support streaming responses. See the [Prediction API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-prediction-api/overview#enable-streaming) for examples of curl calls and streaming output. **2025-10-16** # Accelerated indexing with Lucidworks AI batch vectorization Lucidworks AI continues to advance the performance of vector-based indexing. The latest release introduces new batch vectorization capability that significantly improves embedding throughput. Fusion 5.9.15 now supports this capability through the [LWAI Batch Vectorize Index Stage](/docs/5/fusion/reference/config-ref/pipeline-stages/index-stages/lwai-batch-vectorize-index-stage), enabling faster and more scalable document processing. This integration shows how Fusion and Lucidworks AI evolve together to deliver higher performance for AI-driven indexing. > **[Fusion](/docs/5/fusion/operations/fusion-5-upgrades)** > > Upgrade to Fusion 5.9.15 to take advantage of the new **LWAI Batch Vectorize Index Stage** and achieve faster, more scalable indexing performance. Follow the Fusion upgrade guide to complete your upgrade. > **[Lucidworks Search](https://support.lucidworks.com/hc/en-us/articles/360052984674-Submit-a-Managed-Fusion-promotion-request-for-a-Production-environment)** > > Lucidworks Search customers can request an upgrade to Fusion 5.9.15 to enable the new **LWAI Batch Vectorize Index Stage** and benefit from significantly improved indexing performance. Contact your Lucidworks representative to initiate the upgrade process. The **LWAI Batch Vectorize Index Stage** groups documents and sends them together to the Lucidworks AI embedding endpoint. By batching requests, it minimizes API overhead, increases throughput, and improves overall pipeline efficiency. ## Performance improvements Benchmark testing shows that using the**LWAI Batch Vectorize Index Stage** achieved indexing speeds up to 10 times faster than the single-document approach. Indexing rates reached as high as 95 documents per second, compared to fewer than 8 documents per second previously. Even with larger embeddings, throughput consistently exceeded 80 documents per second. ## How it works The **LWAI Batch Vectorize Index Stage** buffers documents until either the maximum batch size or the maximum wait time is reached. The batch is then sent to the Lucidworks AI embedding service in a single API call, reducing overhead and enabling more consistent scaling. ![Flowchart for single document processing](https://mintcdn.com/lucidworks/zvKMB9iXJuSZcsZs/assets/images/5.9/vectorize-single.png?fit=max\&auto=format\&n=zvKMB9iXJuSZcsZs\&q=85\&s=991f3ddee404aae884595c8779fca176) Flowchart for single document processing The new stage allows multiple documents per API call, reducing latency and improving performance through Lucidworks AI’s optimized embedding infrastructure. ![Flowchart for batch document processing](https://mintcdn.com/lucidworks/zvKMB9iXJuSZcsZs/assets/images/5.9/vectorize-batch.png?fit=max\&auto=format\&n=zvKMB9iXJuSZcsZs\&q=85\&s=4c99cd2e80e4af6abbd64c59f6def397) Flowchart for batch document processing ## Integrated product development This release demonstrates how Lucidworks AI innovations directly influence Fusion’s evolution. The **LWAI Batch Vectorize Index Stage** enables Fusion users to take advantage of Lucidworks AI’s optimized batching and embedding capabilities without changing existing configurations. This release highlights how Fusion and Lucidworks AI are being developed in parallel to deliver practical improvements. By adopting the new Batch Vectorize stage, Lucidworks AI users benefit from faster indexing and greater scalability without needing to change their embedding configuration. For details on setup and configuration, see the [LWAI Batch Vectorize Index Stage documentation](/docs/5/fusion/reference/config-ref/pipeline-stages/index-stages/lwai-batch-vectorize-index-stage). **2025-08-08** **Introducing Agent Studio** Lucidworks is pleased to announce the launch of Agent Studio, a new capability on Lucidworks Platform that enables organizations to create and deploy AI-powered virtual agents for their websites. These prebuilt, customizable agents address a wide range of use cases, including product question-and-answer experiences and generative AI summarization. ![Agent Studio Q\&A](https://mintcdn.com/lucidworks/xIt5gcpMw2KY9W-W/assets/images/lw-platform/agent-studio.svg?fit=max\&auto=format\&n=xIt5gcpMw2KY9W-W\&q=85\&s=e1487dcaa2edf3ae22a4c4ba49a4d300) ### Designed for B2B and B2C Agent Studio supports both B2B and B2C commerce strategies. For B2B organizations, virtual agents can guide customers through complex product specifications, compatibility requirements, and contract terms, helping shorten sales cycles. For B2C retailers, agents can answer product-specific questions about features, ingredients, or usage guidelines, giving customers the confidence to complete purchases. ![Agent Studio Q\&A](https://mintcdn.com/lucidworks/xIt5gcpMw2KY9W-W/assets/images/lw-platform/agent-studio-custom.svg?fit=max\&auto=format\&n=xIt5gcpMw2KY9W-W\&q=85\&s=ac2cbc4c38a80a95258d1f58fab735ec) ### Business impact Virtual agents are available 24/7 to handle high inquiry volumes, reducing wait times and live interaction demands. This enables staff to focus on resolving complex cases, accelerating transaction completion, and improving customer satisfaction. By integrating directly into product pages, agents deliver accurate, contextual information without requiring customers to search multiple documents. ### Key features * Library of prebuilt agent types, including Product Q\&A agents optimized for industry and use case. * Integration with Google Cloud Platform (GCP) datasources for secure, cloud-based data ingestion. * Simple deployment with a script and HTML snippet. * Multiple options for product ID extraction to ensure accurate, product-specific answers. * Customizable layout through CSS to match website branding. ### Get started Agent Studio is available now in Lucidworks Platform. Select an agent type from the library, connect your datasource, choose an AI model for your industry, and implement the agent with a few lines of code. You can preview and refine the agent before it goes live, ensuring accurate, optimized responses. > **[Agent Studio](/docs/lw-platform/lw-agent-studio/overview)** > > Explore the Agent Studio documentation to discover how to create, customize, and deploy AI-powered virtual agents for your business. **2025-06-11** Core Settings is a new capability that simplifies how organizations design and manage search experiences. It provides a single place to configure critical elements of search, including relevance, boost, and typeahead, without requiring code or infrastructure changes. ![Boost in Core Settings](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/sites/core-settings-boost.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=8fd2040b685dfdc99035e45d46414bff) This release introduces an intuitive workflow that makes advanced features accessible in minutes. For example, teams can adjust Neural Hybrid Search by setting the balance between lexical and semantic approaches through a simple slider. What previously required technical expertise can now be managed through a straightforward interface, giving more teams direct control over search quality. ![Neural Hybrid Search in Core Settings](https://mintcdn.com/lucidworks/FtDps0vG_MOhPC6g/assets/images/lw-platform/sites/core-settings-nhs.png?fit=max\&auto=format\&n=FtDps0vG_MOhPC6g\&q=85\&s=7ffbeea5ba3d5cb42ed52067f92a50df) The benefits of Core Settings extend beyond configuration. The preferences defined here establish a consistent foundation that carries through to Commerce Studio and other applications. This creates a shared understanding of the optimal search setup across environments, ensuring users and customers encounter relevant, high quality results. > **Benefits for B2B commerce** > > B2B buyers often work with large, complex catalogs and need precise access to products or parts. Core Settings enables fine control over relevance, making it easier to surface the right items quickly. Boosting rules and typeahead help reduce friction in product discovery and speed up workflows, which supports efficiency for procurement teams and sales operations. > **Benefits for B2C commerce** > > B2C customers expect fast, personalized experiences that feel intuitive. Core Settings allows merchandising and digital teams to tune search in ways that highlight trending products, balance semantic understanding with exact keyword matches, and provide responsive typeahead suggestions. These adjustments improve product findability, reduce abandonment, and support higher conversion rates across retail and consumer channels. Core Settings enables organizations to move faster, align teams around a unified search strategy, and deliver improved experiences to both business buyers and consumers. > **[Core Settings](/docs/lw-platform/lw-core/overview)** > > Use Core Settings to quickly define how search works across your applications. Adjust relevance, apply boosting rules, enable typeahead, and fine tune Neural Hybrid Search with no coding necessary. **2025-05-14** **Lucidworks AI now supports chunking** Lucidworks AI now uses document chunking to deliver more precise search results and AI-generated responses from large files. Chunking breaks documents into smaller, meaningful sections so the system can identify and return the most relevant part, rather than the entire document. This capability is available in Fusion 5.9.12 and later. This delivers: * **More accurate answers**: Generative AI uses the most relevant sections, improving accuracy and reducing irrelevant output. * **Better context**: Responses are grounded in the specific parts of a document that match the prompt. * **Fresher content**: Updates and removals apply at the section level, ensuring AI uses current information. * **Improved ranking**: Search and AI results can prioritize the best-matching chunks instead of entire documents. [Enable chunking in Fusion](https://app.supademo.com/embed/cmbjyucmh00j9xu0j0vmhkoum?embed_v=2\&utm_source=embed) Five chunking strategies are available: * **dynamic-newline**: Breaks text at newline characters, adjusting chunk size automatically. * **dynamic-sentence**: Groups sentences together with flexible chunk length based on context. * **regex-splitter**: Uses a custom regular expression to define chunk boundaries. * **semantic**: Organizes content into sections based on meaning and related ideas. * **sentence**: Creates chunks from single sentences or a set number of sentences, based on configuration. In B2B and B2C commerce, these strategies help AI find exact product details, specifications, or terms hidden deep in large catalogs, manuals, and contracts, improving customer experiences and sales efficiency. > **[Chunking in Fusion 5.9](/docs/5/fusion/reference/config-ref/pipeline-stages/index-stages/lucidworks-ai-chunker-index-stage)** > > Discover how to use Lucidworks AI to chunk documents for improved retrieval, relevance, and ranking in Fusion 5.9. # Conversational Q&A agent Source: https://doc.lucidworks.com/docs/lw-platform/lw-agent-studio/conversational-qna Set up an Agent Studio chat agent that answers natural-language questions about a product, grounded in its documentation. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio The **Conversational Q\&A** agent is an AI-powered chat agent that lives on your product detail pages. Customers ask natural-language questions about a product, and the agent responds with accurate, real-time answers grounded in that product's own documentation, such as datasheets, manuals, specifications, and other supporting PDF technical content. The agent answers follow-up questions in the same session. ## Use cases **B2B** If you are a B2B organization that provides computer components for enterprise organizations, your customers may ask questions about the specifications and compatibility documents for your products prior to purchase. The Conversational Q\&A agent can interpret user questions, analyze the documentation, and quickly provide accurate, factually-based answers. Any follow-up questions are answered based on the information on your site. This saves your customers time-consuming and difficult research to obtain the information they need to help make a purchasing decision. This agent enhances customer satisfaction, increases the potential for conversions, and improves the long-term relationship between your customers and your organization. **B2C** The Conversational Q\&A agent is most effective for B2C organizations that offer products with complex documentation such as technical specifications and requirements. For example, a customer asks about the installation and warranty for an uninterruptible power supply for their office computer. The agent interprets the user's questions and returns relevant, concise information derived from the documents on your site. As the customer enters additional questions, the agent responds with answers to those inquiries. This enhances the potential for sales, and minimizes customer support calls or product returns. **Knowledge management** The Conversational Q\&A agent excels at knowledge management use cases, helping employees and stakeholders quickly surface institutional knowledge from internal documentation, policies, and procedures. For example, an HR team member asks about the company's parental leave policy and accrual rules. Instead of searching through multiple documents, the agent interprets the question and returns a clear, accurate summary drawn from official HR documentation. As the employee asks follow-up questions such as eligibility criteria or how to submit a request, the agent continues the conversation with contextually relevant answers. This reduces time spent searching for information and keeps teams aligned on internal processes. ## Set up the agent This section details how to create, configure, and test the Conversational Q\&A agent. > **Prepare your data** > > Agent Studio reads your data from a Google Cloud Storage (GCS) bucket outside of Lucidworks Platform. > You enter the bucket details when you create the agent. > If your organization doesn't have a GCS bucket to use as a datasource, see [Create a GCS bucket](https://cloud.google.com/storage/docs/creating-buckets). > > Your data must be in JSONL *and* PDF format. > > In a JSONL file, each line is a complete JSON expression representing a single document, as in the example below: > > ```json wrap theme={"dark"} > {"name": "Puffy Winter Jacket", "product_id": "7a45q835", "description": "This classic down-filled jacket provides maximum insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} > {"name": "Extra Puffy Winter Jacket", "product_id": "9b82c222", "description": "This classic down-filled jacket provides even more insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} > ``` > > * All fields are required. > * Each `product_id` must be unique. > * JSONL lines are not separated by commas. > * Enter multiple PDF files as an array of strings. > * If a document doesn't have an associated PDF file, a blank PDF file is accepted. > **Create the agent** > > 1. From the **Agent Studio** screen, select **Agents** and click **+ Create New**. > > ![Create a custom agent](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-qna-name-select-agent.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=eebd5386b880170223fa66a5106d58c7) > > 2. Enter a descriptive **Name** for the agent, select **Conversational Q\&A**, and then click **Next**. > > ![Select an industry domain and model](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-qna-select-domain-model.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=fa48cf2f1cda5824b3b854affdc8769c) > > 3. From the **Industry Domain** list, select the industry that best matches your business. > > 4. In the **Tasks** field, select the AI model to execute for the agent. > The recommended model for your industry is selected by default, but you can select a different model. > Click **Next**. > > 5. On the **Select a data connector** screen, click **GCS Bucket** and then click **Next**. > > 6. On the **Configure GCS bucket to import data** screen, fill out all required fields. > > ![GCS bucket configuration](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-create-agent-gcs-bucket.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=a7a011d209a6519f93b07efa27fe50d7) > > * In the **Name** field, enter the name of your datasource as you want it to display in Lucidworks Platform. > * In the **Processing Region** field, select the region for Lucidworks to process your data. This is not necessarily the region you created your GCS bucket in. The default value is `us-southcarolina`. > * In the **Bucket Name** field, enter the name of your GCS bucket as it displays in GCS. > * In the **Service Account JSON Key** field, enter your Google Cloud Platform (GCP) key in JSON format to allow access to your GCS bucket. > > 7. Click **Verify Connection** to verify the connection to the GCS bucket. > > > [!NOTE] > > > > You can add multiple GCS buckets to expand the information the model uses for responses. > > To add another bucket, click **Add New** on the **Configure GCS bucket** screen. > > To remove a bucket, select it and click **Remove**. > > 8. When the agent is created, choose what to do next: > > * **Preview Agent** opens the agent preview, where you enter a product ID and test the agent's responses in Agent Studio before you add it to your site. > See [Preview and test the agent](#preview-and-test-the-agent). > * **Get Agent Code** displays the code snippets to add the agent to your website. > See [Embed the agent](#embed-the-agent). > > You can also click **Exit** and do either later from the agent details. > Verify the agent displays on the **Agents** screen. > > ![Preview Agent or Get Agent Code](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-select-preview-or-get-agent-code.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=fa7c34cf15be1dd441426fd5eaab6924) > > > [!WARNING] > > > > Major changes to an agent, such as updating the model or changing datasources, generate a new `template-id`. > > The old `template-id` still works, but it may not reflect your changes. > > Update your frontend code with the new `template-id` from the agent's **Details** tab to use the latest configuration. > **Preview and test the agent** > > Preview an agent in Agent Studio to test its responses before you add it to your website. > The preview displays the same component your customers see, using live data from your datasource for the product ID you enter. > You don't need to embed the agent or configure the **Agent Code** section to use the preview. > > 1. Navigate to Agent Studio, click the **Agents** tab, and then select the agent you want to preview or test. > > ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) > > The agent details display the following sections: > > * **Agent Information**, such as the name, type, and model for the agent. > * **Agent Preview**, to test whether the responses accurately reflect the information on your website. > * **Agent Code**, to embed the agent in your web page. > > 2. In the **Agent Preview** section, enter the ID of a product from your datasource. > The agent loads using the data for that product. > If the product ID isn't found, check the ID and try again. > > What the preview displays depends on the agent type: > > * **Product Q\&A** displays the questions and answers generated for the product. Select a question to view its answer. > * **Conversational Q\&A** opens a chat. Enter questions about the product, including follow-up questions. > * **Conversational Q\&A FAQ** opens a chat for your questions and displays generated questions a customer is likely to ask. > > 3. Test the agent's responses and verify they accurately reflect the information about that product. > > > [!NOTE] > > > > If the preview reports that no data is available, your datasource is still processing or contains no documents. > > Wait for the initial processing to finish, and then try again. > **Embed the agent** > > After you create an agent, the agent details screen provides the code to embed the agent on your website. > Embedding an agent involves two decisions: > > * Where you [place the script](#add-the-script) that loads the agent. > > * How the agent [obtains the product ID](#specify-the-product-id) so it provides accurate information. > > > [!NOTE] > > > > The script, component markup, and CSS are unique to each agent. > > Always copy the code from the **Agent Details** section of the agent you're embedding. > > ### Add the script > > 1. Navigate to Agent Studio, click **Agents**, and then click the agent you want to implement. > > ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) > > 2. In the **Agent Details** section, scroll to the **Agent Code** section, and in the **Add the Script Tag** area, click **Copy**. > > ![Agent Code section](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-implement-markup-attribute.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=1242f69e5a73f29b11cd8b7cf715e5e6) > > 3. Paste the script into the `` or `` of your website's HTML. > > No matter where you place the script, the `` snippet must be in the `` of a page for the agent to display there. > > **In the \ (recommended)** > > For best performance, place the script in the ``. > The script loads before the page body, along with any other scripts in your ``. > The agent displays only on pages where you also place the `` snippet in the ``. > > ```html theme={"dark"} > > > > > > > > > ``` > > **In the \** > > If you place the script in the `` of specific pages, it loads only on those pages, after the scripts in your ``. > The order of the script and snippet relative to other items on the page can affect the order in which other page elements load, so this placement isn't recommended. > > ```html theme={"dark"} > > > > > > > > > > ``` > > > [!NOTE] > > > > If your site uses a Content Security Policy (CSP), add `https://storage.googleapis.com` to your `script-src` directive (the agent script is served from Google Cloud Storage) and add the App Studio API URL to your `connect-src` directive. > > > [!NOTE] > > > > To use the Signals beacon on the same page as your agent, you need additional script configuration. > > See [Configure the beacon with Agent Studio or UI Studio](/docs/lw-platform/lw-analytics/signals/signals-beacon#configure-the-beacon-with-agent-studio-or-ui-studio). > > ### Specify the product ID > > The agent answers questions about a specific product. > It identifies the product by its unique ID, which it gets from the `` snippet in the `` of your page. > > Choose one of the following methods, and use it with the script placement you chose in [Add the script](#add-the-script). > > #### URL query parameter > > Use this method when the product ID is consistently in the page URL as a query parameter, or when you want to avoid manually injecting it into the HTML snippet. > > 1. Scroll to the **Add Component Markup** section, and then in the **Automatic Extraction** area, click **Copy**. > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > 3. In the **Specify the Product ID** section, enter the **URL Query Parameters** value for the product ID. > For example, if your URL is `https://www.example.com/sale?q=solvents&product=1234` and your product ID is `1234`, enter `product`. > 4. Verify the agent displays on the appropriate pages of your website. > 5. Test the agent by entering various queries to determine if it returns appropriate responses. > > #### CSS selector > > Use this method when the product ID isn't in a URL query parameter, you don't want to inject it into the HTML snippet, and the product ID is already on the page in an element you can isolate with CSS selectors. > > > [!NOTE] > > > > You must be able to extract the exact product ID through CSS selectors. > > For example, if the product ID is `1234`, you must be able to extract `1234` without any additional text, such as `product-id: 1234`. > > 1. Scroll to the **Add Component Markup** section, and then in the **Automatic Extraction** area, click **Copy**. > > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > > 3. In the **Specify the Product ID** section, enter the **CSS Selector** that contains the product ID. > The following example uses `.product .product-name @data-value` to extract a product ID of `1234`: > > ```html theme={"dark"} > > > > > >
>
> Product Name >
>
> > > > > ``` > > 4. Verify the agent displays on the appropriate pages of your website. > > 5. Test the agent by entering various queries to determine if it returns appropriate responses. > > #### Markup attribute > > Use this method when the product ID exists on the product detail page but isn't available in the HTML or as a query parameter. > You inject the product ID dynamically into the markup. > > 1. Scroll to the **Add Component Markup** section, and then in the **Markup Attribute** area, click **Copy**. > > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > The following example uses `https://www.example.com/sale/1234` and `product-id` in the snippet. > If your product ID attribute name is different from the one in the copied snippet, change the attribute name manually. > > ```html theme={"dark"} > > > > > > > > > ``` > > 3. Verify the agent displays on the appropriate pages of your website. > > 4. Test the agent by entering various queries to determine if it returns appropriate responses. > > ### Customize the layout with CSS > > The agent details screen also contains a CSS code block. > Use it to customize the appearance of the agent to match your website's existing layout. > > The following example shows some custom styling options. > Styling options vary by agent type. > > > [!NOTE] > > > > All agent customizations must be contained within the `.lw-template` properties. > > ```css theme={"dark"} > /* Custom styling for the agent template */ > .lw-template { > /* Container dimensions */ > min-height: 300px; > max-height: 800px; > min-width: 300px; > max-width: 600px; > > /* Optional styling examples: */ > --qna-font-family: Arial, sans-serif; > --qna-container-border-radius: 10px; > --qna-header-font-size: 32px; > --qna-header-icon-color: #a19eff; > --qna-answer-bubble-bg-color: #add8e6; > } > ``` ## Manage the agent > **[Manage agents](/docs/lw-platform/lw-agent-studio/manage-agents)** > > Preview, edit, and delete agents. # Conversational Q&A FAQ agent Source: https://doc.lucidworks.com/docs/lw-platform/lw-agent-studio/conversational-qna-faq Set up an Agent Studio agent that answers natural-language questions about a product and generates related frequently asked questions. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio The **Conversational Q\&A FAQ** agent combines the [Conversational Q\&A agent](/docs/lw-platform/lw-agent-studio/conversational-qna) with generated frequently asked questions: * **Answers to initial and follow-up queries.** The agent assesses user queries and analyzes product information, specifications, and other documents on your site to generate standardized, accurate, content-based answers. If the user enters additional questions, the agent continues the conversation. * **Frequently asked questions.** The agent generates a series of questions the current user is most likely to ask. This gives the user more information about their query, which can help minimize customer support calls and product returns. [Conversational Q\&A FAQ agent example](https://app.supademo.com/embed/cmords7yg44fdw9dophsneqci?embed_v=2\&utm_source=embed) ## Use cases **B2B** If you are a B2B organization that provides computer components for enterprise organizations, your customers may ask questions about the specifications and compatibility documents for your products prior to purchase. The Conversational Q\&A FAQ agent can interpret user questions, analyze the documentation, and quickly provide accurate, factually-based answers. The agent responds to any follow-up queries to continue the conversation, providing standardized answers based on your site's documentation. In addition, the agent predicts and surfaces several relevant questions based on the product content itself, which may provide information the current user might not have thought to ask. This gives the user more information to understand the product, and helps minimize customer support calls and product returns. **B2C** If you are a B2C organization that sells exercise equipment, a customer could ask about a specific treadmill. The agent reviews product information and provides answers to the user query. If the customer enters additional questions about price, payment options, and delivery options, the agent responds with fact-based answers from the information on your site. The agent may also provide a list of frequently asked questions about financing options, assembly instructions, and recommended assemblers. This conversation and section of frequently asked questions can help the customer make the choice that is best for them, which increases customer satisfaction and minimizes support interactions and product returns. **Knowledge management** If your organization wants to provide human resource documents such as sick leave policies or code of conduct requirements, the agent can answer employee questions in natural language and surface the most relevant content from those documents. It also generates frequently asked questions based on the available documentation, helping employees self-serve before reaching out to HR. This reduces the burden on HR teams and ensures employees consistently receive accurate, policy-aligned answers. ## Set up the agent This section details how to create, configure, and test the Conversational Q\&A FAQ agent. > **Prepare your data** > > Agent Studio reads your data from a Google Cloud Storage (GCS) bucket outside of Lucidworks Platform. > You enter the bucket details when you create the agent. > If your organization doesn't have a GCS bucket to use as a datasource, see [Create a GCS bucket](https://cloud.google.com/storage/docs/creating-buckets). > > Your data must be in JSONL *and* PDF format. > > In a JSONL file, each line is a complete JSON expression representing a single document, as in the example below: > > ```json wrap theme={"dark"} > {"name": "Puffy Winter Jacket", "product_id": "7a45q835", "description": "This classic down-filled jacket provides maximum insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} > {"name": "Extra Puffy Winter Jacket", "product_id": "9b82c222", "description": "This classic down-filled jacket provides even more insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} > ``` > > * All fields are required. > * Each `product_id` must be unique. > * JSONL lines are not separated by commas. > * Enter multiple PDF files as an array of strings. > * If a document doesn't have an associated PDF file, a blank PDF file is accepted. > **Create the agent** > > This agent uses two AI models: one for the generated FAQ (**Q\&A Generation**) and one for the conversation (**Conversation Generation**). > > 1. From the **Agent Studio** screen, select **Agents** and click **+ Create New**. > > ![Create a custom agent](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-faq-name-select-agent.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=fd9a7fc3545606f415f14c2b240e4203) > > 2. Enter a descriptive **Name** for the agent, select **Conversational Q\&A FAQ**, and then click **Next**. > > ![Select an industry domain and model](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-faq-domain-create-agent-domain-model.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=d436646ba5acff5743223896245031e4) > > 3. From the **Industry Domain** list, select the industry that best matches your business. > > ![Select an industry domain](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-faq-create-agent-domain-model1.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=3a18c268ccadbc1a5a8f82295c233517) > > 4. In the **Tasks** field, select the AI model to execute for **Q\&A Generation**. > The recommended model for your industry is selected by default, but you can select a different model. > > ![Select the Q\&A Generation model](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-faq-create-agent-domain-model2.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=6606175940b3517f372c5d0d809cb7dd) > > 5. In the **Tasks** field, select the AI model to execute for **Conversation Generation**. > The recommended model for your industry is selected by default, but you can select a different model. > Click **Next**. > > 6. On the **Select a data connector** screen, click **GCS Bucket** and then click **Next**. > > 7. On the **Configure GCS bucket to import data** screen, fill out all required fields. > > ![GCS bucket configuration](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-create-agent-gcs-bucket.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=a7a011d209a6519f93b07efa27fe50d7) > > * In the **Name** field, enter the name of your datasource as you want it to display in Lucidworks Platform. > * In the **Processing Region** field, select the region for Lucidworks to process your data. This is not necessarily the region you created your GCS bucket in. The default value is `us-southcarolina`. > * In the **Bucket Name** field, enter the name of your GCS bucket as it displays in GCS. > * In the **Service Account JSON Key** field, enter your Google Cloud Platform (GCP) key in JSON format to allow access to your GCS bucket. > > 8. Click **Verify Connection** to verify the connection to the GCS bucket. > > > [!NOTE] > > > > You can add multiple GCS buckets to expand the information the model uses for responses. > > To add another bucket, click **Add New** on the **Configure GCS bucket** screen. > > To remove a bucket, select it and click **Remove**. > > 9. When the agent is created, choose what to do next: > > * **Preview Agent** opens the agent preview, where you enter a product ID and test the agent's responses in Agent Studio before you add it to your site. > See [Preview and test the agent](#preview-and-test-the-agent). > * **Get Agent Code** displays the code snippets to add the agent to your website. > See [Embed the agent](#embed-the-agent). > > You can also click **Exit** and do either later from the agent details. > Verify the agent displays on the **Agents** screen. > > ![Preview Agent or Get Agent Code](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-select-preview-or-get-agent-code.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=fa7c34cf15be1dd441426fd5eaab6924) > > > [!WARNING] > > > > Major changes to an agent, such as updating the model or changing datasources, generate a new `template-id`. > > The old `template-id` still works, but it may not reflect your changes. > > Update your frontend code with the new `template-id` from the agent's **Details** tab to use the latest configuration. > **Preview and test the agent** > > Preview an agent in Agent Studio to test its responses before you add it to your website. > The preview displays the same component your customers see, using live data from your datasource for the product ID you enter. > You don't need to embed the agent or configure the **Agent Code** section to use the preview. > > 1. Navigate to Agent Studio, click the **Agents** tab, and then select the agent you want to preview or test. > > ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) > > The agent details display the following sections: > > * **Agent Information**, such as the name, type, and model for the agent. > * **Agent Preview**, to test whether the responses accurately reflect the information on your website. > * **Agent Code**, to embed the agent in your web page. > > 2. In the **Agent Preview** section, enter the ID of a product from your datasource. > The agent loads using the data for that product. > If the product ID isn't found, check the ID and try again. > > What the preview displays depends on the agent type: > > * **Product Q\&A** displays the questions and answers generated for the product. Select a question to view its answer. > * **Conversational Q\&A** opens a chat. Enter questions about the product, including follow-up questions. > * **Conversational Q\&A FAQ** opens a chat for your questions and displays generated questions a customer is likely to ask. > > 3. Test the agent's responses and verify they accurately reflect the information about that product. > > > [!NOTE] > > > > If the preview reports that no data is available, your datasource is still processing or contains no documents. > > Wait for the initial processing to finish, and then try again. > **Embed the agent** > > After you create an agent, the agent details screen provides the code to embed the agent on your website. > Embedding an agent involves two decisions: > > * Where you [place the script](#add-the-script) that loads the agent. > > * How the agent [obtains the product ID](#specify-the-product-id) so it provides accurate information. > > > [!NOTE] > > > > The script, component markup, and CSS are unique to each agent. > > Always copy the code from the **Agent Details** section of the agent you're embedding. > > ### Add the script > > 1. Navigate to Agent Studio, click **Agents**, and then click the agent you want to implement. > > ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) > > 2. In the **Agent Details** section, scroll to the **Agent Code** section, and in the **Add the Script Tag** area, click **Copy**. > > ![Agent Code section](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-implement-markup-attribute.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=1242f69e5a73f29b11cd8b7cf715e5e6) > > 3. Paste the script into the `` or `` of your website's HTML. > > No matter where you place the script, the `` snippet must be in the `` of a page for the agent to display there. > > **In the \ (recommended)** > > For best performance, place the script in the ``. > The script loads before the page body, along with any other scripts in your ``. > The agent displays only on pages where you also place the `` snippet in the ``. > > ```html theme={"dark"} > > > > > > > > > ``` > > **In the \** > > If you place the script in the `` of specific pages, it loads only on those pages, after the scripts in your ``. > The order of the script and snippet relative to other items on the page can affect the order in which other page elements load, so this placement isn't recommended. > > ```html theme={"dark"} > > > > > > > > > > ``` > > > [!NOTE] > > > > If your site uses a Content Security Policy (CSP), add `https://storage.googleapis.com` to your `script-src` directive (the agent script is served from Google Cloud Storage) and add the App Studio API URL to your `connect-src` directive. > > > [!NOTE] > > > > To use the Signals beacon on the same page as your agent, you need additional script configuration. > > See [Configure the beacon with Agent Studio or UI Studio](/docs/lw-platform/lw-analytics/signals/signals-beacon#configure-the-beacon-with-agent-studio-or-ui-studio). > > ### Specify the product ID > > The agent answers questions about a specific product. > It identifies the product by its unique ID, which it gets from the `` snippet in the `` of your page. > > Choose one of the following methods, and use it with the script placement you chose in [Add the script](#add-the-script). > > #### URL query parameter > > Use this method when the product ID is consistently in the page URL as a query parameter, or when you want to avoid manually injecting it into the HTML snippet. > > 1. Scroll to the **Add Component Markup** section, and then in the **Automatic Extraction** area, click **Copy**. > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > 3. In the **Specify the Product ID** section, enter the **URL Query Parameters** value for the product ID. > For example, if your URL is `https://www.example.com/sale?q=solvents&product=1234` and your product ID is `1234`, enter `product`. > 4. Verify the agent displays on the appropriate pages of your website. > 5. Test the agent by entering various queries to determine if it returns appropriate responses. > > #### CSS selector > > Use this method when the product ID isn't in a URL query parameter, you don't want to inject it into the HTML snippet, and the product ID is already on the page in an element you can isolate with CSS selectors. > > > [!NOTE] > > > > You must be able to extract the exact product ID through CSS selectors. > > For example, if the product ID is `1234`, you must be able to extract `1234` without any additional text, such as `product-id: 1234`. > > 1. Scroll to the **Add Component Markup** section, and then in the **Automatic Extraction** area, click **Copy**. > > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > > 3. In the **Specify the Product ID** section, enter the **CSS Selector** that contains the product ID. > The following example uses `.product .product-name @data-value` to extract a product ID of `1234`: > > ```html theme={"dark"} > > > > > >
>
> Product Name >
>
> > > > > ``` > > 4. Verify the agent displays on the appropriate pages of your website. > > 5. Test the agent by entering various queries to determine if it returns appropriate responses. > > #### Markup attribute > > Use this method when the product ID exists on the product detail page but isn't available in the HTML or as a query parameter. > You inject the product ID dynamically into the markup. > > 1. Scroll to the **Add Component Markup** section, and then in the **Markup Attribute** area, click **Copy**. > > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > The following example uses `https://www.example.com/sale/1234` and `product-id` in the snippet. > If your product ID attribute name is different from the one in the copied snippet, change the attribute name manually. > > ```html theme={"dark"} > > > > > > > > > ``` > > 3. Verify the agent displays on the appropriate pages of your website. > > 4. Test the agent by entering various queries to determine if it returns appropriate responses. > > ### Customize the layout with CSS > > The agent details screen also contains a CSS code block. > Use it to customize the appearance of the agent to match your website's existing layout. > > The following example shows some custom styling options. > Styling options vary by agent type. > > > [!NOTE] > > > > All agent customizations must be contained within the `.lw-template` properties. > > ```css theme={"dark"} > /* Custom styling for the agent template */ > .lw-template { > /* Container dimensions */ > min-height: 300px; > max-height: 800px; > min-width: 300px; > max-width: 600px; > > /* Optional styling examples: */ > --qna-font-family: Arial, sans-serif; > --qna-container-border-radius: 10px; > --qna-header-font-size: 32px; > --qna-header-icon-color: #a19eff; > --qna-answer-bubble-bg-color: #add8e6; > } > ``` ## Manage the agent > **[Manage agents](/docs/lw-platform/lw-agent-studio/manage-agents)** > > Preview, edit, and delete agents. # Manage agents Source: https://doc.lucidworks.com/docs/lw-platform/lw-agent-studio/manage-agents Preview, edit, and delete Agent Studio agents. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio After you create an agent, you can preview, edit, or delete it from the **Agents** screen in Agent Studio. ## Preview and test an agent Preview an agent in Agent Studio to test its responses before you add it to your website. The preview displays the same component your customers see, using live data from your datasource for the product ID you enter. You don't need to embed the agent or configure the **Agent Code** section to use the preview. 1. Navigate to Agent Studio, click the **Agents** tab, and then select the agent you want to preview or test. ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) The agent details display the following sections: * **Agent Information**, such as the name, type, and model for the agent. * **Agent Preview**, to test whether the responses accurately reflect the information on your website. * **Agent Code**, to embed the agent in your web page. 2. In the **Agent Preview** section, enter the ID of a product from your datasource. The agent loads using the data for that product. If the product ID isn't found, check the ID and try again. What the preview displays depends on the agent type: * **Product Q\&A** displays the questions and answers generated for the product. Select a question to view its answer. * **Conversational Q\&A** opens a chat. Enter questions about the product, including follow-up questions. * **Conversational Q\&A FAQ** opens a chat for your questions and displays generated questions a customer is likely to ask. 3. Test the agent's responses and verify they accurately reflect the information about that product. > [!NOTE] > > If the preview reports that no data is available, your datasource is still processing or contains no documents. > Wait for the initial processing to finish, and then try again. ## Edit an agent 1. Navigate to Agent Studio, click **Agents**, hold the pointer over the agent you want to change, and click the pencil icon. 2. Enter the changes on each screen, clicking **Next** to advance to the next screen, and then click **Exit** on the final screen to save the changes. 3. [Preview and test the agent](#preview-and-test-an-agent) to verify the changes. If necessary, refine the agent until the returned responses are accurate and optimized. > [!WARNING] > > Major changes to an agent, such as updating the model or changing datasources, generate a new `template-id`. > The old `template-id` still works, but it may not reflect your changes. > Update your frontend code with the new `template-id` from the agent's **Details** tab to use the latest configuration. If your changes generate a new `template-id`, update the `` snippet on your site. For embedding details, select your agent type in [Configure and deploy an agent](/docs/lw-platform/lw-agent-studio/overview#configure-and-deploy-an-agent). ## Delete an agent 1. Navigate to Agent Studio, click **Agents**, hold the pointer over the agent you want to delete, and then click the trash can icon. 2. Confirm the deletion, and then verify the agent no longer displays on the **Agents** screen. > [!WARNING] > > Deleting an agent is permanent. > To use a deleted agent again, you must create it as a new agent. # Agent Studio Source: https://doc.lucidworks.com/docs/lw-platform/lw-agent-studio/overview Create prebuilt, customizable AI agents that answer customer questions on your website. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio Agent Studio lets you create AI-powered virtual agents for your website. Agents are prebuilt, highly customizable solutions for use cases such as product question and answer widgets and conversational chat agents that respond to multiple questions in a single session. They improve customer experiences for B2B, B2C, and knowledge management organizations. Virtual agents provide the following benefits: * They're available 24/7 to customers all over the world and respond with accurate, standardized information tailored to each query. * They handle high volumes of inquiries, which reduces wait times and live customer interactions, so your personnel can focus on more complex issues. ## How Agent Studio works **Agents come from a prebuilt library.** Choose the agent type that fits your use case, and then configure it for your business. **Your data stays in your GCS bucket.** Agent Studio reads JSONL and PDF content from Google Cloud Storage (GCS) buckets that you connect to the agent. **Models are matched to your industry.** Select your industry domain, and Agent Studio recommends the generative AI model to use. You can select a different model. Agent Studio doesn't support custom large language model (LLM) training. **Agents embed with a script and one HTML element.** Add the agent's script and `` snippet to your site, and the agent displays on those pages. ## Get started > **[Quickstart](/docs/lw-platform/lw-agent-studio/quickstart)** > > Create and embed your first agent. > **[Agent Studio for Commerce and Knowledge Management](https://academy.lucidworks.com/scorm/01a13b7a-8775-70e7-991d-5eb12e6e0164)** > > Learn how to choose the right agent for commerce and knowledge management use cases, connect it to your data in a GCS bucket, and embed it on your site. ## Configure and deploy an agent This demo shows how to create and deploy an agent in Agent Studio. [https://app.supademo.com/embed/cmosvfabg011w1j0jmgtg1uza?embed\_v=2\&utm\_source=embed](https://app.supademo.com/embed/cmosvfabg011w1j0jmgtg1uza?embed_v=2\&utm_source=embed) Select an agent type to display detailed instructions to configure and deploy that agent on your site. > **[Product Q\&A](/docs/lw-platform/lw-agent-studio/product-qna)** > > Generate frequently asked questions and answers about a product from its documentation. > **[Conversational Q\&A](/docs/lw-platform/lw-agent-studio/conversational-qna)** > > Answer natural-language questions and follow-ups about a product, grounded in its documentation. > **[Conversational Q\&A FAQ](/docs/lw-platform/lw-agent-studio/conversational-qna-faq)** > > Combine conversational answers with generated frequently asked questions. ## Manage an existing agent > **[Manage agents](/docs/lw-platform/lw-agent-studio/manage-agents)** > > Preview, edit, and delete agents. # Product Q&A agent Source: https://doc.lucidworks.com/docs/lw-platform/lw-agent-studio/product-qna Set up an Agent Studio agent that generates frequently asked questions and answers about a product from its documentation. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio The **Product Q\&A** agent generates frequently asked questions and answers about a product or document, based on your industry and the information on your website. Customers select a question to view its answer without reading multiple documents. ## Use cases **B2B** If you are a B2B organization that provides industrial technology components and a computer server manufacturer queries about fiber optic connectors, the agent displays questions that a customer may have about a specific fiber optic connector on its product detail page, based on the information ingested about that product in the datasource from documents such as instruction manuals and specification files. These questions could relate to bandwidth capabilities, equipment compatibility, and warranty terms. The customer can then select the question to view the answer without reading multiple documents to find the answer. **B2C** If you are a B2C organization that provides skin care products, the agent displays questions that a customer may have about a specific skin care product on its product detail page, based on the information ingested about that product in the datasource from documents such as ingredient lists and benefits of using that product. These questions could relate to whether that product is vegan or suitable for daily use. The customer can then select the question and view the answer, increasing customer confidence and the likelihood of a purchase. ## Set up the agent This section details how to create, configure, and test the Product Q\&A agent. > **Prepare your data** > > Agent Studio reads your data from a Google Cloud Storage (GCS) bucket outside of Lucidworks Platform. > You enter the bucket details when you create the agent. > If your organization doesn't have a GCS bucket to use as a datasource, see [Create a GCS bucket](https://cloud.google.com/storage/docs/creating-buckets). > > Your data must be in JSONL *and* PDF format. > > In a JSONL file, each line is a complete JSON expression representing a single document, as in the example below: > > ```json wrap theme={"dark"} > {"name": "Puffy Winter Jacket", "product_id": "7a45q835", "description": "This classic down-filled jacket provides maximum insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} > {"name": "Extra Puffy Winter Jacket", "product_id": "9b82c222", "description": "This classic down-filled jacket provides even more insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} > ``` > > * All fields are required. > * Each `product_id` must be unique. > * JSONL lines are not separated by commas. > * Enter multiple PDF files as an array of strings. > * If a document doesn't have an associated PDF file, a blank PDF file is accepted. > **Create the agent** > > 1. From the **Agent Studio** screen, select **Agents** and click **+ Create New**. > > ![Create a custom agent](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-prod-qna-name-select-agent.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=d5f22c69667c20bc606d54779cf7a4a3) > > 2. Enter a descriptive **Name** for the agent, select **Product Q\&A**, and then click **Next**. > > ![Select an industry domain and model](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-prod-qna-create-agent-domain-model.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=272f9893ff62370ce54c7a82c84ee03d) > > 3. From the **Industry Domain** list, select the industry that best matches your business. > > 4. In the **Tasks** field, select the AI model to execute for the agent. > The recommended model for your industry is selected by default, but you can select a different model. > Click **Next**. > > 5. On the **Select a data connector** screen, click **GCS Bucket** and then click **Next**. > > 6. On the **Configure GCS bucket to import data** screen, fill out all required fields. > > ![GCS bucket configuration](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-create-agent-gcs-bucket.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=a7a011d209a6519f93b07efa27fe50d7) > > * In the **Name** field, enter the name of your datasource as you want it to display in Lucidworks Platform. > * In the **Processing Region** field, select the region for Lucidworks to process your data. This is not necessarily the region you created your GCS bucket in. The default value is `us-southcarolina`. > * In the **Bucket Name** field, enter the name of your GCS bucket as it displays in GCS. > * In the **Service Account JSON Key** field, enter your Google Cloud Platform (GCP) key in JSON format to allow access to your GCS bucket. > > 7. Click **Verify Connection** to verify the connection to the GCS bucket. > > > [!NOTE] > > > > You can add multiple GCS buckets to expand the information the model uses for responses. > > To add another bucket, click **Add New** on the **Configure GCS bucket** screen. > > To remove a bucket, select it and click **Remove**. > > 8. When the agent is created, choose what to do next: > > * **Preview Agent** opens the agent preview, where you enter a product ID and test the agent's responses in Agent Studio before you add it to your site. > See [Preview and test the agent](#preview-and-test-the-agent). > * **Get Agent Code** displays the code snippets to add the agent to your website. > See [Embed the agent](#embed-the-agent). > > You can also click **Exit** and do either later from the agent details. > Verify the agent displays on the **Agents** screen. > > ![Preview Agent or Get Agent Code](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-select-preview-or-get-agent-code.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=fa7c34cf15be1dd441426fd5eaab6924) > > > [!WARNING] > > > > Major changes to an agent, such as updating the model or changing datasources, generate a new `template-id`. > > The old `template-id` still works, but it may not reflect your changes. > > Update your frontend code with the new `template-id` from the agent's **Details** tab to use the latest configuration. > **Preview and test the agent** > > Preview an agent in Agent Studio to test its responses before you add it to your website. > The preview displays the same component your customers see, using live data from your datasource for the product ID you enter. > You don't need to embed the agent or configure the **Agent Code** section to use the preview. > > 1. Navigate to Agent Studio, click the **Agents** tab, and then select the agent you want to preview or test. > > ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) > > The agent details display the following sections: > > * **Agent Information**, such as the name, type, and model for the agent. > * **Agent Preview**, to test whether the responses accurately reflect the information on your website. > * **Agent Code**, to embed the agent in your web page. > > 2. In the **Agent Preview** section, enter the ID of a product from your datasource. > The agent loads using the data for that product. > If the product ID isn't found, check the ID and try again. > > What the preview displays depends on the agent type: > > * **Product Q\&A** displays the questions and answers generated for the product. Select a question to view its answer. > * **Conversational Q\&A** opens a chat. Enter questions about the product, including follow-up questions. > * **Conversational Q\&A FAQ** opens a chat for your questions and displays generated questions a customer is likely to ask. > > 3. Test the agent's responses and verify they accurately reflect the information about that product. > > > [!NOTE] > > > > If the preview reports that no data is available, your datasource is still processing or contains no documents. > > Wait for the initial processing to finish, and then try again. > **Embed the agent** > > After you create an agent, the agent details screen provides the code to embed the agent on your website. > Embedding an agent involves two decisions: > > * Where you [place the script](#add-the-script) that loads the agent. > > * How the agent [obtains the product ID](#specify-the-product-id) so it provides accurate information. > > > [!NOTE] > > > > The script, component markup, and CSS are unique to each agent. > > Always copy the code from the **Agent Details** section of the agent you're embedding. > > ### Add the script > > 1. Navigate to Agent Studio, click **Agents**, and then click the agent you want to implement. > > ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) > > 2. In the **Agent Details** section, scroll to the **Agent Code** section, and in the **Add the Script Tag** area, click **Copy**. > > ![Agent Code section](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-implement-markup-attribute.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=1242f69e5a73f29b11cd8b7cf715e5e6) > > 3. Paste the script into the `` or `` of your website's HTML. > > No matter where you place the script, the `` snippet must be in the `` of a page for the agent to display there. > > **In the \ (recommended)** > > For best performance, place the script in the ``. > The script loads before the page body, along with any other scripts in your ``. > The agent displays only on pages where you also place the `` snippet in the ``. > > ```html theme={"dark"} > > > > > > > > > ``` > > **In the \** > > If you place the script in the `` of specific pages, it loads only on those pages, after the scripts in your ``. > The order of the script and snippet relative to other items on the page can affect the order in which other page elements load, so this placement isn't recommended. > > ```html theme={"dark"} > > > > > > > > > > ``` > > > [!NOTE] > > > > If your site uses a Content Security Policy (CSP), add `https://storage.googleapis.com` to your `script-src` directive (the agent script is served from Google Cloud Storage) and add the App Studio API URL to your `connect-src` directive. > > > [!NOTE] > > > > To use the Signals beacon on the same page as your agent, you need additional script configuration. > > See [Configure the beacon with Agent Studio or UI Studio](/docs/lw-platform/lw-analytics/signals/signals-beacon#configure-the-beacon-with-agent-studio-or-ui-studio). > > ### Specify the product ID > > The agent answers questions about a specific product. > It identifies the product by its unique ID, which it gets from the `` snippet in the `` of your page. > > Choose one of the following methods, and use it with the script placement you chose in [Add the script](#add-the-script). > > #### URL query parameter > > Use this method when the product ID is consistently in the page URL as a query parameter, or when you want to avoid manually injecting it into the HTML snippet. > > 1. Scroll to the **Add Component Markup** section, and then in the **Automatic Extraction** area, click **Copy**. > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > 3. In the **Specify the Product ID** section, enter the **URL Query Parameters** value for the product ID. > For example, if your URL is `https://www.example.com/sale?q=solvents&product=1234` and your product ID is `1234`, enter `product`. > 4. Verify the agent displays on the appropriate pages of your website. > 5. Test the agent by entering various queries to determine if it returns appropriate responses. > > #### CSS selector > > Use this method when the product ID isn't in a URL query parameter, you don't want to inject it into the HTML snippet, and the product ID is already on the page in an element you can isolate with CSS selectors. > > > [!NOTE] > > > > You must be able to extract the exact product ID through CSS selectors. > > For example, if the product ID is `1234`, you must be able to extract `1234` without any additional text, such as `product-id: 1234`. > > 1. Scroll to the **Add Component Markup** section, and then in the **Automatic Extraction** area, click **Copy**. > > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > > 3. In the **Specify the Product ID** section, enter the **CSS Selector** that contains the product ID. > The following example uses `.product .product-name @data-value` to extract a product ID of `1234`: > > ```html theme={"dark"} > > > > > >
>
> Product Name >
>
> > > > > ``` > > 4. Verify the agent displays on the appropriate pages of your website. > > 5. Test the agent by entering various queries to determine if it returns appropriate responses. > > #### Markup attribute > > Use this method when the product ID exists on the product detail page but isn't available in the HTML or as a query parameter. > You inject the product ID dynamically into the markup. > > 1. Scroll to the **Add Component Markup** section, and then in the **Markup Attribute** area, click **Copy**. > > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > The following example uses `https://www.example.com/sale/1234` and `product-id` in the snippet. > If your product ID attribute name is different from the one in the copied snippet, change the attribute name manually. > > ```html theme={"dark"} > > > > > > > > > ``` > > 3. Verify the agent displays on the appropriate pages of your website. > > 4. Test the agent by entering various queries to determine if it returns appropriate responses. > > ### Customize the layout with CSS > > The agent details screen also contains a CSS code block. > Use it to customize the appearance of the agent to match your website's existing layout. > > The following example shows some custom styling options. > Styling options vary by agent type. > > > [!NOTE] > > > > All agent customizations must be contained within the `.lw-template` properties. > > ```css theme={"dark"} > /* Custom styling for the agent template */ > .lw-template { > /* Container dimensions */ > min-height: 300px; > max-height: 800px; > min-width: 300px; > max-width: 600px; > > /* Optional styling examples: */ > --qna-font-family: Arial, sans-serif; > --qna-container-border-radius: 10px; > --qna-header-font-size: 32px; > --qna-header-icon-color: #a19eff; > --qna-answer-bubble-bg-color: #add8e6; > } > ``` ## Manage the agent > **[Manage agents](/docs/lw-platform/lw-agent-studio/manage-agents)** > > Preview, edit, and delete agents. # Quickstart Source: https://doc.lucidworks.com/docs/lw-platform/lw-agent-studio/quickstart > **Key questions to get you started** > > Powered by Lucidworks Agent Studio This quickstart explains how to create an embeddable AI agent. Agent Studio provides a simple interface for quickly creating an intelligent agent that can answer customer questions right inside your website. For a video walkthrough of the setup steps for a new agent, click **Get Started** below: [https://app.supademo.com/embed/cmosvfabg011w1j0jmgtg1uza?embed\_v=2\&utm\_source=embed](https://app.supademo.com/embed/cmosvfabg011w1j0jmgtg1uza?embed_v=2\&utm_source=embed) Here's how it works: **1. Define your use case** What business goals will this agent help you meet? In what context will customers encounter this agent? What types of questions do your customers ask? Knowing the answers to these questions helps you choose the right type of agent and the right content to train it for maximum effectiveness. **2. Format your training data** Agent Studio reads data directly from a GCS bucket, not from Fusion. Your data must be in JSONL *and* PDF format. In a JSONL file, each line is a complete JSON expression representing a single document, as in the example below: ```json wrap theme={"dark"} {"name": "Puffy Winter Jacket", "product_id": "7a45q835", "description": "This classic down-filled jacket provides maximum insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} ``` For the complete data requirements, select your agent type in [Configure and deploy an agent](/docs/lw-platform/lw-agent-studio/overview#configure-and-deploy-an-agent). **3. Select an agent from the Agent Studio library** Your library includes one or more pre-built agent templates, depending on your Lucidworks subscription. Navigate to the Agent Studio Library screen and click the agent that's best suited for your use case. To compare agent types, see [Configure and deploy an agent](/docs/lw-platform/lw-agent-studio/overview#configure-and-deploy-an-agent). You can [contact Lucidworks](mailto:support@lucidworks.com) if you need additional agent templates for the evolving needs of your business. **4. Configure your agent** Agent Studio guides you through some simple setup steps to connect your agent to your data. You can also configure options that help train your agent to provide the most helpful answers for your customers, such as the industry domain and the AI model to use. When you finish configuring your agent, Lucidworks AI needs some time to perform the initial training that fully enables it. While training is in progress, you can update your website code as explained in the final step below. You can also preview and test your agent right inside Agent Studio. Click the **Agents** tab, and then select the agent you want to preview or test. The Agent Details display. The **Agent Preview** section lets you test the agent to determine if the responses accurately reflect the information on your website. ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) **5. Embed the agent code on your site** Now you're ready to embed the agent where your customers will see it. Click **Get Agent Code** to get ready-to-use code snippets that you can copy and paste into your site code: * Copy the ` ``` **2. Customize the configuration** Every site works a little differently. The Signals Beacon is flexible, so you can set it up in the way that fits your site best. To get started, configure the Signals Beacon to collect these user insights: > **Queries** > > When users search for products, they land on a search results page. They might use facets to narrow down what they see. > > Capture the user's search query and selected facets. Map the query and facet parameters from the URL to the `query` field in the Signals Beacon configuration. > > ```html URL theme={"dark"} > https://example.com/search?q=USER_QUERY&fq=color:("red","pink") > ``` > > ```json Query Config highlight={22-30} theme={"dark"} > { > "attributes": { > "idQueryParam": "pid", > "numberTypeFields": [ > "price", > "quantity", > "revenue" > ], > "productPath": ".resultsItem" > }, > "cartAdd": { > "trigger": ".lw-cart-add-trigger" > }, > "click": {}, > "fields": { > "productId": ":scope .resultId @text", > "title": ":scope .itemTitle @text" > }, > "purchase": { > "trigger": ".lw-purchase-trigger" > }, > "query": { > "facets": { > "keyValueDelimiter": ":", > "queryParams": "fq", > "valueExtractorRegex": "/\\\"(.*)\\\"/", > "valuesDelimiter": "," > }, > "queryParam": "q" > } > } > ``` > **Clicks** > > When users find a product they like, they click on it. > > Capture that interaction. Map the product ID from the HTML to the `click` and `fields` fields in the Signals Beacon configuration. > > > [!NOTE] > > > > The `click` field inherits values from the `fields` field. It’s recommended to use the `fields` field directly. > > ```html HTML highlight={3-4} theme={"dark"} >
> >
12345
>
Wireless Noise-Canceling Headphones
> >
> ``` > > ```json Click Config highlight={14-18} theme={"dark"} > { > "attributes": { > "idQueryParam": "pid", > "numberTypeFields": [ > "price", > "quantity", > "revenue" > ], > "productPath": ".resultsItem" > }, > "cartAdd": { > "trigger": ".lw-cart-add-trigger" > }, > "click": {}, > "fields": { > "productId": ":scope .resultId @text", > "title": ":scope .itemTitle @text" > }, > "purchase": { > "trigger": ".lw-purchase-trigger" > }, > "query": { > "facets": { > "keyValueDelimiter": ":", > "queryParams": "fq", > "valueExtractorRegex": "/\\\"(.*)\\\"/", > "valuesDelimiter": "," > }, > "queryParam": "q" > } > } > ``` > **Cart adds** > > When users add a product to their shopping cart, that action shows strong interest and intent to buy. > > Capture this interaction by mapping the click from your HTML to the `cartAdd` field in the Signals Beacon configuration. Tracking this helps you understand what products matter most and where users may drop off before purchasing. > > ```html HTML highlight={7} theme={"dark"} >
>
>
12345
>
Wireless Noise-Canceling Headphones
>
199.99
>
> >
> ``` > > ```json Cart Add Config highlight={11-13} theme={"dark"} > { > "attributes": { > "idQueryParam": "pid", > "numberTypeFields": [ > "price", > "quantity", > "revenue" > ], > "productPath": ".resultsItem" > }, > "cartAdd": { > "trigger": ".lw-cart-add-trigger" > }, > "click": {}, > "fields": { > "productId": ":scope .resultId @text", > "title": ":scope .itemTitle @text" > }, > "purchase": { > "trigger": ".lw-purchase-trigger" > }, > "query": { > "facets": { > "keyValueDelimiter": ":", > "queryParams": "fq", > "valueExtractorRegex": "/\\\"(.*)\\\"/", > "valuesDelimiter": "," > }, > "queryParam": "q" > } > } > ``` > **Purchases** > > One of the most important actions that drives your business is a user purchase. When users complete the checkout process, it confirms their decision to buy. > > Make sure to capture this event. Map the relevant HTML to the purchase field in the Signals Beacon configuration. > > ```html HTML highlight={9} theme={"dark"} >
>
>
12345
>
Wireless Noise-Canceling Headphones
>
1
>
199.99
>
199.99
>
> >
> ``` > > ```json Purchase Config highlight={19-21} theme={"dark"} > { > "attributes": { > "idQueryParam": "pid", > "numberTypeFields": [ > "price", > "quantity", > "revenue" > ], > "productPath": ".resultsItem" > }, > "cartAdd": { > "trigger": ".lw-cart-add-trigger" > }, > "click": {}, > "fields": { > "productId": ":scope .resultId @text", > "title": ":scope .itemTitle @text" > }, > "purchase": { > "trigger": ".lw-purchase-trigger" > }, > "query": { > "facets": { > "keyValueDelimiter": ":", > "queryParams": "fq", > "valueExtractorRegex": "/\\\"(.*)\\\"/", > "valuesDelimiter": "," > }, > "queryParam": "q" > } > } > ``` **3. Turn it on** When you're ready to start collecting user insights in Lucidworks Analytics using the Signals Beacon, activate it in the **Integrations** screen. Add your site to the list of **Allowed origins**. ![](https://mintcdn.com/lucidworks/iWKi6k5BBzt8DXQ0/assets/images/lw-platform/analytics/signals-beacon-allowed-origins.png?fit=max\&auto=format\&n=iWKi6k5BBzt8DXQ0\&q=85\&s=11c9934f2f6c6f3ee8f6099c84826c0f) Sites added to the allowed origins with the Signals Beacon installed start collecting user insights instantly. Once added, the Signals Beacon starts sending user insights to Lucidworks Analytics. Your **Signals analytics** dashboard will begin to show key metrics. # Signals Source: https://doc.lucidworks.com/docs/lw-platform/lw-analytics/signals/overview [old doc.lw link]: https://doc.lucidworks.com/lw-platform/analytics/0le96f [localhost link]: http://localhost:3000/docs/lw-platform/lw-analytics/signals/overview [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-analytics/signals/overview The signals features in Analytics Studio include the [signals beacon](/docs/lw-platform/lw-analytics/signals/signals-beacon), a lightweight script tag that gathers query (including selected facets), click, cart-add, and purchase complete signals from customer interactions on your website and the [Signals Store](/docs/lw-platform/lw-analytics/signals/signals-store) for the designated workspace where signals are stored. Instead of using the signals beacon, you can manually configure and maintain code in your backend codebase by using the [Signals API](/docs/lw-platform/lw-analytics/signals/signals-api) to send signals to Analytics Studio. This method is useful if you need to send signals from your backend, rather than a website or frontend application, or if your website does not support JavaScript. > [!TIP] > > Lucidworks adheres to strict data privacy and security policies, including General Data Protection Regulation (GDPR) compliance, when collecting and storing signals. Security features include user IP address anonymization, exclusion of personally-identifiable information, and secure storage. The policies also provide guidelines and best practices to help clients implement compliant configurations. To review the detailed policies, see [Lucidworks Signals Beacon Privacy and Security policies](/docs/policies/lw-signals-beacon) and [GDPR Compliance policy](/docs/policies/lw-signals-beacon-gdpr-compliance). The following signals are collected: * **Query signals.** When a user performs a search, a signal is recorded. * **Click signals.** When a user clicks on a product, a signal is recorded. One example of a click signal is when a user clicks a search result, which is a strong indicator the result is relevant. * **Cart-add signals.** When a user clicks to add an item to the cart, a signal is recorded. * **Purchase complete signals.** When a user completes a purchase and is taken to the order confirmation page, a signal is recorded. * **Facet usage.** When a user applies a facet, a new query signal is recorded that includes the selected facets. If present in the signal, the information collected by the signals beacon and housed in the Signals Store for each signal is: * Product ID * Title * Image URI * Price > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Overview of signals process This section provides an overview of how to implement the use of signals in Analytics Studio. More information is detailed in additional topics. 1. Analyze the queries, clicks, cart-adds, and purchases on your site to determine areas that could be strengthened to enhance your company’s goals. 2. Create the [Signals Store](/docs/lw-platform/lw-analytics/signals/signals-store) for the designated workspace. For example, you may have a testing workspace and a production workspace. The Signals Store for the testing workspace may contain data that would not be available in your production site. 3. Add the [signals beacon](/docs/lw-platform/lw-analytics/signals/signals-beacon) to the `` section of your site. This includes not only header information, but specific field identifiers for the signals based on your site analysis. When the signals beacon is added, signals are: * Gathered by the signals beacon * Stored in the Signals Store * Sent to [Analytics Studio metrics](/docs/lw-platform/lw-analytics/analytics-screen) that provide valuable customer behavior insights and can be used to improve your business # Signal Usage Metrics Source: https://doc.lucidworks.com/docs/lw-platform/lw-analytics/signals/signal-usage The Signal Usage screen displays global signal usage metrics for a specified date range. Here you can see the total volume of signals from all of your signals buckets, distinguished by signal type. You can use this screen to confirm that signals are flowing into the system so that you can use them in Analytics Studio, Commerce Studio, or anywhere signals are displayed. This graph lets you identify issues with signal intake and take prompt action to adapt settings and configuration to prevent issues that might be caused by missing signals or incomplete data. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio Click your organization type for information about the benefits of using the Signal Usage screen: **Business-to-Consumer** These metrics reflect user behavior patterns that help you improve product offerings and campaigns that enhance the customer search experience and increase conversions. For example, a significant increase during a promotional campaign helps confirm the success of the event, and lets you adjust the campaign to increase conversions. **Business-to-Business** The Signal Usage screen helps your organization monitor data flow and identify ingestion and other issues quickly, which enhances the ability to maintain operational efficiency. For example, if a significant decrease in signals occurs, you can troubleshoot automated workflows and other areas to determine the cause. **Knowledge Management** Signal usage metrics provide information about relevance, ranking, and discoverability of site content. For example, a decrease in signals can indicate users may not be finding the information they need. A review of relevance settings and potential content gaps could help resolve any issues. To access the Signal Usage screen, open the megamenu and click **Signals**, then click the **Signal Usage** tab. ![Signal usage](https://mintcdn.com/lucidworks/s9t4aQbBH7Ek57zN/assets/images/lw-platform/analytics/signal-usage.png?fit=max\&auto=format\&n=s9t4aQbBH7Ek57zN\&q=85\&s=abd1d88099802e6b20dbb78eb7278ad1) Click **Get Started** below for a quick demo that shows you how to navigate to the Signal Usage screen and explore your signal data. [Signal Usage Metrics in Lucidworks Platform](https://app.supademo.com/embed/cmhtppd9h2m6s11r6nccnepn1?embed_v=2\&utm_source=embed) # Signals Beacon Source: https://doc.lucidworks.com/docs/lw-platform/lw-analytics/signals/signals-beacon [old doc.lw link]: https://doc.lucidworks.com/lw-platform/analytics/k649vy [localhost link]: http://localhost:3000/docs/lw-platform/lw-analytics/signals/signals-beacon [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-analytics/signals/signals-beacon The signals beacon is an embeddable tracker that captures signals corresponding to user actions, like searches and purchases. Add the beacon script to your site's `` once. After that, you can manage what it captures entirely from Lucidworks Platform. No further code changes or deployments to your site are required. At a high level, the tracking flow begins when a user visits the site and performs one or more searches. These searches generate query identifiers that associate user actions with specific queries. As the user interacts with search results and shows interest in a product, additional signals such as clicks and cart events are captured. If the user completes a purchase, the flow concludes with a purchase signal. Each purchased product is linked to the query that led to its cart-add. This process enables end-to-end tracking of user behavior from search to purchase. In this scenario, the signals beacon uses several primary tracking mechanisms: * **Visitor ID**: A randomly generated identifier stored in local browser storage. It is unique to both the visitor and the device. It persists across sessions. * **Session ID**: A randomly generated identifier that the beacon uses to track and assign signals to sessions. It is stored in local browser storage under the `lwBeaconSessionId` key. It expires after 30 minutes of inactivity. This duration is configurable using `sessionTimeoutThreshold`. Each signal resets the inactivity timer, and the session ID persists across tabs and page reloads. When the user returns after the session expires, a new session ID is generated, but the visitor ID remains the same. * **Query ID**: A randomly generated identifier created when a search query is submitted. It is stored in session storage and is included with signal events related to that query, such as clicks and cart-adds. * **Cart ID**: A unique identifier created when a product is added to the cart. It's shared by every cart-add signal and the purchase signal for that cart. Together with product IDs, it links each purchased product to the query that led to its cart-add. After a purchase, a new cart ID is generated to track subsequent transactions independently. The signal event flow below outlines a simplified sequence of common events. Additional signal types and behaviors are not included in this summary: 1. When a user visits the site, a visitor ID and session ID are generated. 2. When a query is submitted, a query ID is generated and a query signal is sent. This signal includes the visitor ID and session ID. 3. For each new query, a new query ID is generated and another query signal is sent. 4. When the user clicks on a product, a click signal is sent. This signal includes the associated query ID. 5. When the user adds a product to their cart, a cart-add signal is sent with the current query ID and cart ID. If there's no cart ID yet, one is generated. 6. When the user completes a purchase and lands on the order confirmation page, a purchase signal is sent. This signal includes the order ID and the current cart ID. The purchase signal doesn't include a query ID. Each purchased product is traced to its query through the cart ID and product ID. After the signal is sent, the cart ID is replaced with a new one to track future transactions independently. See the following image for a visual representation of this flow: ![Simplified signals beacon flow](https://mintcdn.com/lucidworks/eLUenv1bWKGXrswG/assets/images/lw-platform/analytics/signalsbeaconflow.png?fit=max\&auto=format\&n=eLUenv1bWKGXrswG\&q=85\&s=01001c00e288fbfe041380ffe27b6581) > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## How it works The beacon sends signals to the: * [Signals store](/docs/lw-platform/lw-analytics/signals/signals-store) for storage and aggregation * [Analytics Studio service](/docs/lw-platform/lw-analytics/overview), which provides insights about actions taken by users on your site The following signals are collected: * **Query signals.** When a user performs a search, a signal is recorded. * **Click signals.** When a user clicks on a product, a signal is recorded. One example of a click signal is when a user clicks a search result, which is a strong indicator the result is relevant. * **Cart-add signals.** When a user clicks to add an item to the cart, a signal is recorded. * **Purchase complete signals.** When a user completes a purchase and is taken to the order confirmation page, a signal is recorded. * **Facet usage.** When a user applies a facet, a new query signal is recorded that includes the selected facets. For information about how the signals beacon is related to other signals and analytics functions, see the [Overview of signals process](/docs/lw-platform/lw-analytics/signals/overview). ## Prerequisites You must be a workspace owner to configure the signals beacon. Before you begin, complete the following tasks: * Analyze your site to confirm compatibility with the signals beacon. The signals beacon is compatible with most websites, but you may need to adjust the configuration to ensure it works as needed. * Your site should use URL query parameters (`?q=foo`), not other methods of sending the query parameters. If it is not an option to use query parameters on your site, you can use the [Signals API](/docs/lw-platform/lw-analytics/signals/signals-api) to send signals. - These fields should be surfaced in the page source, either as attributes or text nodes: * Product ID * Product title * Product image URL * Product price * Product URL * Identify any other fields that you want the signals beacon to capture. You’ll need their CSS paths to configure the beacon. Again, these can be either attributes or text nodes, as in these examples: ```html theme={"dark"}
12345
``` \[!TIP] A field’s path might be different on different pages of your site. The signals beacon supports multiple paths per field to accommodate this. * Create the [Signals Store](/docs/lw-platform/lw-analytics/signals/signals-store) where the signals will be stored. ## Enable the beacon To install the beacon, navigate to the megamenu and click **Signals**. 1. Click the Signals Store where you want to configure the signals beacon and then click **Integrations**. 2. If the beacon has never been configured for this app, you’ll see "No embed token found" on the Signals Using Beacon screen. In that case, click the **Generate** button. It can take a few moments to generate the token. 3. In the **Allowed Origins** field, enter the domains where you want to use the signals beacon. The format is `://[:]`. For example, `https://domain.YOUR_COMPANY_NAME.com`. 4. Set the **Signals Beacon** toggle to **On**. 5. Click **Copy** to copy the script and insert that script into the `` tag of your website’s HTML file. \[!TIP] This also enables the `window.logBeaconInfo()` function which you can use with your browser’s developer tools to inspect the fields captured by the beacon so that you can validate and refine your configuration. See [Development and troubleshooting](#development-and-troubleshooting) below. 6. Edit the JSON configuration to process the signals you need for analytics. For more details, see: * [Example JSON configuration](#example-json-configuration) * [Example signals script](#example-signals-script) * [Field path configuration](#field-path-configuration) * [Beacon Configuration Interface](/docs/lw-platform/lw-analytics/signals/beacon-configuration-interface) for detailed configuration property information 7. Click **Apply**. The configuration is applied to your website and it begins to send signals instantly based on that configuration. > [!NOTE] > > You can edit the configuration at any time. When you edit the JSON configuration and click **Apply**, the changes are applied in real time and signals are sent and processed using that configuration until it is modified. After the script is implemented and the signals are sent, you can access consolidated metrics. The [Analytics Studio metrics](/docs/lw-platform/lw-analytics/analytics-screen) provide valuable customer behavior insights, which can be used to improve your business. ### Example JSON configuration Use the following structure as an example to configure the beacon. ```json lines expandable wrap highlight={13,16,21,27,30-31} JSON configuration theme={"dark"} { "attributes": { "productPath": ".lw-product-item", "sessionTimeoutThreshold": 600000, "cartId": "lwRetailCartId", "idQueryParam": "pid", "numberTypeFields": ["price", "quantity", "revenue"] }, "fields": { "productId": ":scope @id", "imageuri": ":scope img @src", "price": ":scope .search-entity-price span @text", "title": ":scope .search-entity-title @text, :scope .search-generic-title @text", "uri": ".config-url @href" }, "query": { "queryParam": "q", "delayForTrackQueryUpdate": 1000 }, "click": {}, "cartAdd": { "trigger": ".lw-cart-add-trigger" }, "purchase": { "enabled": false }, "purchase_complete": { "urlPattern": "/order-confirmation", "orderIdUrlParam": "orderId", "productPath": ".lw-order-item" } } ``` * **Line 13**. You can use multiple comma-separated paths in cases where a field has different paths on different pages of your site. See the [Field path configuration](#field-path-configuration) section for details and examples. * **Line 16.** Everything below this line is your signal configuration, where you list the signals you want to track and the fields you want to extract from them. * **Line 21.** By default, these attributes inherit from the top-level attributes `[productPath|fields]`. * **Line 27.** Turns off the `purchase` signal, which is sent when the user clicks a checkout element. Because an order can fail after that click, use `purchase_complete` instead. * **Lines 30–31.** Sends a purchase signal when the user lands on a page whose URL contains `/order-confirmation`. The order ID is read from the `orderId` URL query parameter. * **Revenue.** This example doesn't set `revenue`, so the beacon calculates it from each product's price and quantity. If you set `purchase_complete.revenue`, use the item subtotal, not the order total. Revenue shouldn't include tax, shipping, or other fees. For information about: * Attributes and fields used to extract product details from page elements, see the [Field path configuration](#field-path-configuration) section. * The BeaconConfig interface, which includes detailed information about configuration properties, types, and default values, see [Beacon configuration interface](/docs/lw-platform/lw-analytics/signals/beacon-configuration-interface). ### Example signals script The following example contains possible fields and default values. ```json lines wrap expandable highlight={2-5,7-8,14-15,17,34,44,47-50} Signals script theme={"dark"} { "attributes": { "productPath": ".lw-product-item", "cartId": "lwRetailCartId", "numberTypeFields": ["price", "quantity", "revenue"] }, "fields": { "productId": ":scope @id", "title": ".title @text", "imageuri": ".config-image @src", "uri": ".url-wrapper a @href" }, "query": { "queryParam": "query", "delayForTrackQueryUpdate": 1000, "productPath": ".lw-product-item", "fields": { "productId": ":scope @id", "title": ".title @text", "imageuri": ".config-image @src", "uri": ".url-wrapper a @href" } }, "click": { "productPath": ".lw-product-item", "fields": { "productId": ":scope @id", "title": ".title @text", "imageuri": ".config-image @src", "uri": ".url-wrapper a @href" } }, "cartAdd": { "trigger": ".lw-cart-add-trigger", "productPath": ".lw-product-item", "fields": { "productId": ":scope @id", "title": ".title @text", "imageuri": ".config-image @src", "uri": ".url-wrapper a @href" } }, "purchase": { "enabled": false }, "purchase_complete": { "urlPattern": "/order-confirmation", "orderIdUrlParam": "orderId", "delayForPurchaseRedirect": 1000, "productPath": ".lw-order-item", "fields": { "productId": ":scope @data-item-id", "title": ".title @text", "price": ".price @text", "quantity": ".quantity @text" } } } ``` * **Line 2**. Global attributes inherited by each signal section. * **Line 3**. The CSS selector to target product elements. This is the global path inherited by each signal section if no custom path is provided at `[query/click/cartAdd/purchase/purchase_complete].productPath`. The default is `.lw-product-item`. * **Line 4**. The local storage key for the consumer page storing the cart UUID. The `cartId` value defaults to `lwRetailCartId`. The beacon obtains the value from `localStorage.lwRetailCartId` when attaching cart info to `/retail/signals/cartadd ` and `/retail/signals/purchase`. * **Line 5**. This list specifies the fields treated as number type fields. The default is `["price", "quantity", "revenue"]`. * **Line 7**. This is the main section to extract product field value from your site. For more information, see the [Field path configuration](#field-path-configuration) section in this topic, which provides detailed configuration about extracting product information to ensure accurate and consistent data collection. * **Line 8**. The `productId` field with a value of `:scope @id` is the only required field to use the Lucidworks Retail Beacon API. * **Line 14**. Specifies the URL parameter the beacon uses to monitor query updates. For example, with the default param `query`, if the current product page is filtered with the keyword `hat`, the URL parameter is http\://example.com?query=hat. The default value is `query`. * **Line 15**. Specifies the delay, in milliseconds, for tracking element updates in the query. The default value is `1000`. * **Line 17**. Custom overwrite of the fields configuration at the root level. * **Line 34**. The CSS selector that targets page elements for triggering add-to-cart actions. This has full CSS support for targeting multiple elements with comma-separated selectors. For example, `button.add-to-bag, #AddToBagWithPrice`. * **Line 44**. Turns off the `purchase` signal, which is sent when the user clicks a checkout element. Because an order can fail after that click, use `purchase_complete` to track completed purchases. * **Line 47**. The beacon sends a purchase signal when the current URL contains this substring. Use a stable part of your order confirmation page URL. * **Line 48**. The URL query parameter that contains the order ID. Alternatively, use `orderIdSelector` to read the order ID from a page element. * **Line 49**. The delay, in milliseconds, before the beacon reads the confirmation page. Increase this value if your site adds order details to the page after it loads. The default value is `1000`. * **Line 50**. The CSS selector for the purchased items on the confirmation page. If your confirmation page doesn't display purchased items, use a [signal handler](#example-of-a-purchase-complete-signal-from-a-data-layer) to add them. ### Field path configuration The signals beacon extracts product details from page elements using CSS selectors and attributes. You can capture any field that’s surfaced in the page’s DOM by adding it to your JSON configuration, under `"fields"`. This section shows you how to configure your field paths, with examples. The format is: `[Element CSS Selector] @[Value Attribute]`, as in the example below: ```json Configuration theme={"dark"} "url": ".details .url @href" ``` ```html HTML structure theme={"dark"}
...
``` ```bash Data extracted theme={"dark"} http://example.com/prd-123 ``` ### Special selectors These special selectors and attributes are available: * The `@text` pseudo-attribute captures the inner text node, as in these examples: ```json Configuration theme={"dark"} "title": ".title @text" ``` ```html HTML structure theme={"dark"}

Fancy Hat

``` ```bash Data extracted theme={"dark"} Fancy Hat ``` ```json Configuration theme={"dark"} "price": ".details .price @text" ``` ```html HTML structure theme={"dark"}
...
``` ```bash Data extracted theme={"dark"} 100 ``` * The `:scope` CSS class targets product details defined on the root `productPath` element, as in this example: ```json Configuration theme={"dark"} { "attributes": { "productPath": ".main-page-product", }, "fields": { "productId": ":scope @sku", ... } } ``` ```html HTML structure theme={"dark"}
``` ```bash Data extracted theme={"dark"} prd-123 ``` * The `textContent` selector targets elements by their text, as follows: * Exact match: `[textContent='Add to cart!']` * Contains: `[textContent*='cart']` * Starts with: `[textContent^='add']` * Ends with: `[textContent$='cart!']` For example: ```json theme={"dark"} "trigger": "button[textContent='Add to Cart'], .add-to-cart-container button" ``` * You can also use data attributes as selectors, as in this example where `data-testid` is a data attribute: ```json theme={"dark"} "trigger": ".headerSearchBox, #hdrSrch, input[data-testid=global-search]" ``` ### Page type configuration The `pageTypes` configuration enables you to classify queries by page type based on URL patterns. **Configuration:** ```json theme={"dark"} "pageTypes": { "search": ["*/search*"], "category": ["*/category/*"], "product": ["*/product/*"] } ``` **Type:** `{ [pageType: string]: string[] }` A mapping of page types to their corresponding URL patterns. The `pageTypes` configuration enables annotation of query signals via an optional `pageType` property. By default, when no `pageType` is specified, query signals are treated as originating from the search page. When a `pageType` is provided, its value is used for page-type matching. If a query does not match any configured patterns, its `pageType` is set to "OTHER". Queries with a `pageType` other than null or "SEARCH" are excluded from the null query report. This is particularly useful for scenarios where queries originate from or redirect to non-search pages (e.g., category pages). > [!NOTE] > > Explicitly configuring the "search" page type is recommended. Doing so ensures that any query signals from URLs that don't match a configured pattern are classified as "OTHER" and excluded from the null query report. ## Configure the beacon with Agent Studio or UI Studio To use the signals beacon on the same page as Agent Studio or UI Studio, configure the beacon script with additional attributes. Agent Studio and UI Studio both use the `` web component, which requires specific beacon configuration to work correctly. For embedding details, select your agent type in [Configure and deploy an agent](/docs/lw-platform/lw-agent-studio/overview#configure-and-deploy-an-agent). Add the following attributes to the beacon script that you downloaded at **Analytics Studio** > **Integrations**: * `signal-store-api-url`: API URL for your signals store. * `signal-store-embed-token`: Embed token for the signals store. * `beacon="{}"`: Initializes the beacon configuration. * `initiator="AS"`: Identifies the script as being used with Agent Studio or UI Studio. The following example shows the beacon script configured with those additional attributes: ```html {6-9} theme={"dark"} ``` Without these attributes, the beacon and `lw-template` components may conflict and fail to initialize. ## Configure the beacon for multiple pages of search results You can configure the signals beacon if your site separates query results by tabs. For example, one tab for content and another tab for product information. In the following example, each tab’s content path is separated by a comma under `"productPath"` with the `"fields"` property defining what is tracked for each tab using `:scope`. ```json Configuration theme={"dark"} { "attributes": { "numberTypeFields": [ "price", "quantity", "revenue" ], "productPath": ".cmp-content-search-result-list-item, .cmp-productlist__item" }, "click": { "trigger": "a, a h3, .button" }, "fields": { "imageuri": ":scope .cmp-content-search-result-list-item__img @src, :scope img @src", "productId": ":scope .cmp-content-search-result-list-item_link @href, :scope .cmp-text .anchor @text", "title": ":scope .cmp-content-search-result-list-item__details-name @text, :scope .cmp-text p @text", "uri": ":scope .cmp-content-search-result-list-item_link @href" }, "query": { "queryParam": "search_query" } } ``` ## Programmatic hooks Signal handlers modify, enhance, or suppress signals before the beacon sends them. Use a handler when the data you need isn't in the page's Document Object Model (DOM) but is available elsewhere, such as facets stored outside the URL or order details stored in your site's data layer. You can define a handler for each signal type: `query`, `click`, `cartAdd`, `purchase`, and `purchase_complete`. There are two ways to register a handler: * **In the beacon configuration.** Add a `handler` property to the signal section. The value is a function written as a string. The function receives an object with `window` and `payload` properties. * **In your site's code.** Call `window.addBeaconListener` after the beacon loads. The callback receives the signal payload. You can register one handler for each signal type, and you only need to register it once. If a signal type has a handler in both places, the handler in the beacon configuration is used. ### Signal handler behavior The signal handler can be used for the following: * **Modify signals:** return the modified payload object to send an enhanced signal. * **Suppress signals:** return false to prevent the signal from being sent. * **Error handling**: if a runtime error occurs in the callback function, the original unmodified signal will be sent. If the signal handler returns `undefined` or `null`, the unmodified signal will be sent. > [!WARNING] > > Signal handlers run synchronously and must return their result immediately. > Don't use `async` functions or return a `Promise`, because the beacon doesn't wait for it to resolve. The arguments to the `window.addBeaconListener` function should include these: 1. The signal type. 2. Callback function with one argument (signal payload). ### Examples of signal payload enhancement Enhancing a `click` payload: ```js theme={"dark"} window.addBeaconListener('click', (payload) => { // Modify the payload as needed payload.productDetails[0].product.productId = '123'; // Return the modified payload to send the signal return payload; }); ``` Example of a `query` payload: ```js theme={"dark"} window.addBeaconListener('query', (payload) => { // Modify the payload as needed payload.selected_facets = [ { name: 'color', values: ['blue', 'white'], }, ]; // Return the modified payload to send the signal return payload; }); ``` ### Example of conditional signal suppression ```js theme={"dark"} window.addBeaconListener('query', (payload) => { // Do not send query signals that contain a blocked search term if (payload.searchTerms === 'blocked query') { return false; } }); ``` ### Example of a purchase complete signal from a data layer Order confirmation pages often don't display product details in a way the beacon can extract. If your site stores order details in a JavaScript data layer, use a `purchase_complete` handler to build the signal from that data. This example assumes your site pushes an event like the following to `window.dataLayer` when the confirmation page loads. Adjust the property names in the handler to match your site's data layer. ```js Data layer event theme={"dark"} window.dataLayer.push({ event: 'purchase', ecommerce: { transaction_id: 'ORD-12345', currency: 'USD', items: [ { item_id: 'SKU-1001', item_name: 'Fancy Hat', price: 49.99, quantity: 2 }, { item_id: 'SKU-2002', item_name: 'Wool Scarf', price: 29.99, quantity: 1 } ] } }); ``` Add the handler to the `purchase_complete` section of your beacon configuration, or register it in your site's code: ```json Beacon configuration theme={"dark"} "purchase": { "enabled": false }, "purchase_complete": { "urlPattern": "/order-confirmation", "delayForPurchaseRedirect": 2000, "handler": "function({ window, payload }) { const event = (window.dataLayer || []).find(e => e.event === 'purchase' && e.ecommerce); if (!event) return false; const order = event.ecommerce; const productDetails = (order.items || []).map(item => ({ product: { productId: String(item.item_id), title: item.item_name, price: Number(item.price) }, quantity: Number(item.quantity) || 1 })); const revenue = productDetails.reduce((sum, p) => sum + p.product.price * p.quantity, 0); return { ...payload, orderId: String(order.transaction_id), productDetails, revenue }; }" } ``` ```js Site code theme={"dark"} window.addBeaconListener('purchase_complete', (payload) => { const event = (window.dataLayer || []).find((e) => e.event === 'purchase' && e.ecommerce); // Suppress the signal if the order details aren't available if (!event) return false; const order = event.ecommerce; const productDetails = (order.items || []).map((item) => ({ product: { productId: String(item.item_id), title: item.item_name, price: Number(item.price), }, quantity: Number(item.quantity) || 1, })); // Calculate revenue from line items so it excludes tax, shipping, and fees const revenue = productDetails.reduce((sum, p) => sum + p.product.price * p.quantity, 0); return { ...payload, orderId: String(order.transaction_id), productDetails, revenue, }; }); ``` When you build a purchase signal with a handler, keep the following in mind: * **The signal must include products.** The beacon doesn't send a purchase signal with an empty `productDetails` list. * **Product IDs must match your other signals.** Use the same product ID format as your click and cart-add signals, including prefixes and leading zeros. If the formats differ, Analytics Studio can't connect purchases to earlier signals, and conversion metrics are inaccurate. Normalize the IDs in the handler if needed. * **Use the item subtotal for revenue.** Order-level metrics, such as average order value and revenue per visit, use the `revenue` value. Exclude tax, shipping, and other fees so these metrics reflect the value of the purchased items. Product-level reports use each product's `price` and `quantity` instead. * **Allow time for the data layer.** The beacon waits for `delayForPurchaseRedirect` milliseconds before it runs the handler. If your site adds order details to the data layer after the page loads, increase this value. A longer delay increases the chance that the user leaves the page before the signal is sent. ## Content Security Policy (CSP) requirements If your site uses a Content Security Policy (CSP), you must add the following directives to allow the signals beacon to load and send data: * **`script-src`**: Add `https://storage.googleapis.com` because the beacon script is served from Google Cloud Storage. * **`connect-src`**: Add the Signal Store API host and, if using Agent Studio, the App Studio API host. The following example shows the minimum required CSP directives: ```http theme={"dark"} Content-Security-Policy: script-src 'self' https://storage.googleapis.com; connect-src 'self' YOUR_SIGNAL_STORE_API_URL YOUR_APP_STUDIO_API_URL; ``` Replace `YOUR_SIGNAL_STORE_API_URL` with the value in the `signal-store-api-url` attribute of your beacon script, and `YOUR_APP_STUDIO_API_URL` with the value in the `app-studio-api-url` attribute when using Agent Studio. ## Development and troubleshooting The signals beacon includes the built-in `window.logBeaconInfo()` debugging utility that logs verbose information if the debug flag is enabled. To enable the debug flag in your local storage, set `localStorage.enableBeaconDev = true`. # Signals Store Source: https://doc.lucidworks.com/docs/lw-platform/lw-analytics/signals/signals-store [old doc.lw link]: https://doc.lucidworks.com/lw-platform/analytics/88pjp2 [localhost link]: http://localhost:3000/docs/lw-platform/lw-analytics/signals/signals-store [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-analytics/signals/signals-store The Signals Store is the repository in your Lucidworks Platform workspace that holds query, click, cart-add, and purchase complete signals gathered from customer interactions on your site. Facet usage is recorded in query signals. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Create a Signal Store One of the tasks to use signals is to create a repository to store signals. 1. Navigate to the megamenu and click **Signals**. ![Signals store](https://mintcdn.com/lucidworks/eLUenv1bWKGXrswG/assets/images/lw-platform/analytics/signals-store.png?fit=max\&auto=format\&n=eLUenv1bWKGXrswG\&q=85\&s=4b4ac834f6391cf091a7ea25d275529d) 2. Click **Create New**. ![Create a Signals Store](https://mintcdn.com/lucidworks/iWKi6k5BBzt8DXQ0/assets/images/lw-platform/analytics/signals-store-create.png?fit=max\&auto=format\&n=iWKi6k5BBzt8DXQ0\&q=85\&s=92339523bcf0261998451c83ede3dd93) 3. In the **Name** field, enter a unique user-defined for the Signals Store. 4. In the **Region** field, select the geographical area for the Signals Store. > [!NOTE] > > This selection cannot be changed. If you need a Signals Store in a different region, you need to create another Signals Store with the other region specified. 5. Click **Create**. After the Signals Store is created, you can configure the [signals beacon](/docs/lw-platform/lw-analytics/signals/signals-beacon). ## Signal fields stored If present in the signal, the information collected by the signals beacon and housed in the Signals Store for each signal is: * Product ID * Title * Image URI * Price ## Technical components The properties of each Signals Store include: * User-defined name. * Universally unique identifier (`uuid`) of the Signals Store. The `uuid` will be use to generate a unique Signals Store endpoint using the format of `.signals.lucidworks.com`. For more information about signals, see [signals](/docs/lw-platform/lw-analytics/signals/overview). # Core Settings Source: https://doc.lucidworks.com/docs/lw-platform/lw-core/overview [localhost link]: http://localhost:3000/docs/lw-platform/lw-core/overview [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-core/overview [old doc.lw link]: https://doc.lucidworks.com/lw-platform/core/fz448o Core Settings empowers you to build fast, intuitive, and configurable search experiences without the need for complex coding or infrastructure. With Core Settings, you can define and optimize the search experience with just a few clicks. ![Core Settings home screen](https://mintcdn.com/lucidworks/FtDps0vG_MOhPC6g/assets/images/lw-platform/sites/sites-home.png?fit=max\&auto=format\&n=FtDps0vG_MOhPC6g\&q=85\&s=c66c8cd8285b829f00ac5ff1e2d027bf) Each Site comes equipped with essential services to drive intelligent, responsive search, using an interactive UI for setup and tuning. Use the preset defaults to quickly get your search experience up and running. For customization, Core Settings offers controls to adjust performance and relevance. The built-in development environment view gives full visibility into how changes impact search results before going live, so you can test and launch with confidence. To get started, reach out to Lucidworks to request a new site, and we’ll create it for you. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Use cases Core Settings enable tailored search experiences for specific audiences across multiple websites. A multinational ecommerce company can configure search to localize currency, language, and product availability based on regional shipping permissions. Another example is when you have different ecommerce and support websites. The ecommerce website can be set up to search the catalog and datasheets, with an embedded product-finding agent. The support website can be set up to search the knowledge base and include an embedded troubleshooting agent. Sites with multiple query profiles can manage different search configurations for Relevance and Boost settings. Each query profile represents a distinct search experience with its own query pipeline and collection. # Quickstart Source: https://doc.lucidworks.com/docs/lw-platform/lw-core/quickstart Build intuitive and configurable searches in 3 steps. [localhost link]: http://localhost:3000/docs/lw-platform/lw-core/quickstart [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-core/quickstart This quickstart guide helps you set up and optimize your customer's search and browse experience to return the most relevant content for their queries. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio Core settings default values are set based on informed industry standards when you first launch the application. From there, you can tune and evaluate your configuration to best fit your users. > [!NOTE] > > It is essential that you consistently review results and settings in Commerce Studio and Analytics Studio and modify the Core Settings fields to optimize search results for your customers. **1. Refine relevance in search results** Use Neural Hybrid Search (NHS) to take advantage of advanced searching capabilities that combine lexical (Lexical search matches queries to documents based on exact words and character patterns.) search and semantic (Semantic search interprets the meaning of queries to find contextually relevant results, even without exact word matches.) search. ![NHS settings with toggle and slider](https://mintcdn.com/lucidworks/FtDps0vG_MOhPC6g/assets/images/lw-platform/sites/sites-nhs.png?fit=max\&auto=format\&n=FtDps0vG_MOhPC6g\&q=85\&s=b916b7baf20218ecb6fbb21b482d972a) > **Balance between lexical and semantic search** > > Click and drag the Neural Hybrid Search Weight slider to set the level of lexical versus semantic search. User behavior and record types will impact the weight setting. > > To weight exact word entries higher, drag the slider toward **Lexical**. If your products use specific names, SKUs, or other fields such as model number, lexical search is more likely to generate the most relevant results. Lexical search is also more effective for identifying detailed information in specifications and other documents. > > To weight results that interpret the meaning of the query, drag the slider more toward **Semantic**. Semantic search is more helpful if your users tend to enter different terminology for products or enter phrases or complete questions in their queries. > > To determine the effectiveness of this setting, enter multiple searches and review where the query entry displays in the results. You can drag the slider in either direction and test again to determine the optimal setting. > **Control the quality and number of records returned** > > Two settings determine the number of records returned: > > * **Vector Similarity Threshold**: This threshold sets the minimum of how closely a document must match your query's meaning to be included in results. Enter a decimal value between `0` and `1`. > > > [!NOTE] > > > > If you enter a value higher than `1`, an error displays and a rounded down value of `1` defaults in the field. If you enter a negative value less than `0`, an error displays and a rounded up value of `0` defaults in the field. > > * A higher minimum value returns only results that strongly match the query's meaning. Assessing the quality of possible matches to return strong results may increase latency (processing response time). > > * A lower minimum value returns more results because results do not have to match the query's meaning as closely. > > * Results that are not semantically close enough to the query's meaning are filtered out before results are re-ranked. > * **Vector Result Count**: This value specifies how many candidate results the vector (semantic) search retrieves before the results are merged and re-ranked with the lexical results. Enter an integer between `0` and `2000`. > > > [!NOTE] > > > > If you enter a value higher than `2000`, an error displays and a rounded down value of `2000` defaults in the field. If you enter a negative value less than `0`, an error displays and a rounded up value of `0` defaults in the field. > > * A higher value assesses more semantic candidate results, which improves relevant results, but may increase latency (processing response time). > > * A lower value assesses fewer semantic candidate results, which may decrease relevant results, but also takes less processing time. > > > [!NOTE] > > > > These fields map to the `Min Return Vector Similarity` and `Number of Vector Results` fields in the Neural Hybrid Query stage settings in Fusion and Lucidworks Search. > > For guidance about choosing starting values and tuning these settings for your use case, see the [Neural Hybrid Search section of the Relevance topic](/docs/lw-platform/lw-core/sites-relevance#neural-hybrid-search). > [!NOTE] > > The [rules](/docs/lw-platform/lw-cs/cstudio-rules) and [query rewrites](/docs/lw-platform/lw-cs/cstudio-query-rewrite) created in [Commerce Studio](/docs/lw-platform/lw-cs/overview) determine which results display. If results are not as expected, Lucidworks recommends you review and modify the rules and rewrites in Commerce Studio and then adjust the slider. Use the Sort options to display the search results ordered either by relevance (Sort by relevance if the results need to match the query and user intent most closely.) or date (Sort by date if recent results such as the latest regulations or product updates are more important.). For more information, see [Relevance](/docs/lw-platform/lw-core/sites-relevance). ![NHS sort options](https://mintcdn.com/lucidworks/g1p2ZULuslqrEkMX/assets/images/lw-platform/sites/sites-sort.png?fit=max\&auto=format\&n=g1p2ZULuslqrEkMX\&q=85\&s=ee7424ed5db71db9a76be031ef88fbf7) **2. Configure boost parameters** These options let you balance the order in which specific results display. You can adjust the display order of products and information by popularity (The popularity boost provides consistent results for user queries about more stable and long-term products and information.) or recency (The recency boost is more important if newer versions of products or more recent technical or compliance specifications are essential.). For more information, see [Boost](/docs/lw-platform/lw-core/sites-boost). > **Balance between popularity and recency** > > Click and drag the Popularity Boost slider to boost real-time user information from signals. If your products and information are more stable and long-term, the popularity boost provides consistent results for user queries. > > Click and drag the Recency Boost slider if you want to boost recently added or recently modified items or information. For example, if newer versions of products or more recent technical or compliance specifications are essential, the recency boost is more important. ![Boost](https://mintcdn.com/lucidworks/LhpSFYmZLWHv6zvs/assets/images/lw-platform/sites/core-settings-boost-popularity-recency.png?fit=max\&auto=format\&n=LhpSFYmZLWHv6zvs\&q=85\&s=a3683bb7e3ea7e8f65248e519aa71447) You can prioritize certain fields such as SKU or title, if you assign and include them in the Attribute Priority section. Preview the results to determine if the popular versus recent items display as expected, and make changes as needed. Reviewing results and then changing as needed is an ongoing process to obtain optimal results. ![Search attributes](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/sites/sites-boost-saw.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=60aca9064d4a449fcd262253198d22ab) **3. Review analytics and update Core Settings** Lucidworks recommends that you consistently assess your site's analytics and determine where metrics could be improved. [Analytics Studio](/docs/lw-platform/lw-analytics/analytics-screen#types-of-metrics) provides signals graphic overviews for multiple metrics. Important measures such as conversion rate, search conversion rate, and click-through rate help you determine the success of campaigns and other actions. And underperforming products and zero result search rate identify items that may need attention. Modify the Core Settings fields and Commerce Studio features as needed to improve the search experiences of your customers and enhance your company's strategic goals. On an ongoing basis, consistently review analytics and change the settings as needed. # Boost Source: https://doc.lucidworks.com/docs/lw-platform/lw-core/sites-boost Core Settings [localhost link]: http://localhost:3000/docs/lw-platform/lw-core/sites-boost [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-core/sites-boost [old doc.lw link]: https://doc.lucidworks.com/lw-platform/core/mcmjd1 Boosting improves the visibility of items in search results. You can control how items are boosted based on their popularity or newness, plus how specific fields in your data affect boosting. ![Core Settings Boost screen](https://mintcdn.com/lucidworks/e18oRwnR3VuUa79l/assets/images/lw-platform/sites/sites-boost.png?fit=max\&auto=format\&n=e18oRwnR3VuUa79l\&q=85\&s=8f10dd59c69a65ca315a1dd8a84eef2b) > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Query profiles When your site has multiple query profiles, you can select which profile you want to configure using the query profile selector at the top of the Boost page: ![Query profiles dropdown on the Core Settings > Boost page](https://mintcdn.com/lucidworks/e18oRwnR3VuUa79l/assets/images/lw-platform/core-settings/core-settings-boost-query-profiles.png?fit=max\&auto=format\&n=e18oRwnR3VuUa79l\&q=85\&s=afd1f25ded6233e3f4e761e6bf8d7a37) Query profiles enable you to manage multiple search experiences within a single site. Each query profile represents a distinct search configuration, including a query pipeline and collection. > [!NOTE] > > The query profile selector only appears when your site has multiple query profiles configured. > If you have a single query profile, the selector is hidden and all settings apply to that profile automatically. You can create and manage query profiles in [Lucidworks Search](/docs/lucidworks-search/05-move-data-out/query-profile/overview) or [self-hosted Fusion](/docs/5/fusion/getting-data-out/query-basics/query-pipelines/query-profiles), or by contacting Lucidworks. > [!WARNING] > > If two query profiles point to the same query pipeline, changes made to one query profile's Core Settings will impact the other. ## Popularity Boost Increase search result ranking using signals obtained from users, such as how many users clicked on an item, added it to their cart, or purchased it. Using signals requires adding the [signals beacon](/docs/lw-platform/lw-analytics/signals/signals-beacon) to a website or using the [Signals API](/docs/lw-platform/lw-analytics/signals/signals-api) to send signals without the beacon. Adding signals gives you a deeper understanding of user behavior and is useful when deciding how to configure and rank your search results. Popularity Boost uses a discrete slider where you set the degree of how much you want the combined behavior of users to impact the search results. The discrete slider has five settings that range from no boost to full boost. ![Boost signals settings](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/sites/sites-boost-signals.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=c2d87dd0932b383630d67a3bb7b55221) When you increase how much to boost with signals, you give more weight to those signals when ranking search results. More weight means items that users have interacted with more frequently appear higher. This can improve crowd-based relevance, show trending products, and increase conversion rates. There are, however, potential risks of setting the weight too high. For example, products with lower visibility may be pushed down even further. Giving a higher weight to signals can also decrease the impact of curated business rules if not balanced. A best practice is to start with moderate boosting, then evaluate the impact and adjust as needed. This protects important or promoted content you set using business rules or manual boosting. ## Recency Boost You can increase search result ranking based on whether a document was recently added or modified. There are cases when you want a newer item or page to be prioritized above older content as the more recently updated items are often what users are interested in. ![Recency Boost settings](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/sites/sites-boost-fresh.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=a32232e64e88d9bde9d7536200756c86) The Recency Boost slider is where you set the degree of how important it is to show the newest content higher in the search results. A best practice is to start with the moderate setting, then test and tune the weight as needed. If the slider is set too high, you run the risk of surfacing less relevant but recent content over older, more helpful items. If the slider is set too low, users looking for newer content might take longer to find it, causing frustration with outdated or irrelevant top results. ## Attribute Priority You can decide if individual fields should be given priority for user queries. Search attributes can be included or excluded using the dropdown options. ![Search attributes](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/sites/sites-boost-saw.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=60aca9064d4a449fcd262253198d22ab) To see how these fields affect search results, include or exclude the fields relevant to your data and run some queries to analyze their impact. The fields can also be arranged to assign their importance, so the field at the top of the list is given a greater significance than lower fields. Matches on the higher fields are boosted more than matches on the lower ones, and matches on excluded fields don’t affect boosting at all. This is useful when you want to prioritize queries that match the title of an item versus items that have similar words in their descriptions. For example, a query for "handles" would show door handles higher than a cleaning product whose description says it "handles tough stains." # Relevance Source: https://doc.lucidworks.com/docs/lw-platform/lw-core/sites-relevance Core Settings [localhost link]: http://localhost:3000/docs/lw-platform/lw-core/sites-relevance [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-core/sites-relevance [old doc.lw link]: https://doc.lucidworks.com/lw-platform/core/juqsws Relevance optimizes how well the search results match the user’s intent and query. Increasing relevance means happier users through better findability of products and documents. Relevant search results are important for: * E-commerce sites, where relevant results drive conversions and revenue. * Support sections of sites, such as help pages, where relevance reduces customer frustration and complaints. * Enterprise search, where relevance boosts productivity and knowledge discovery by helping employees find what they need to perform their work or solve a problem. ![Core Settings Relevance screen](https://mintcdn.com/lucidworks/FtDps0vG_MOhPC6g/assets/images/lw-platform/sites/sites-home.png?fit=max\&auto=format\&n=FtDps0vG_MOhPC6g\&q=85\&s=c66c8cd8285b829f00ac5ff1e2d027bf) > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Query profiles When your site has multiple query profiles, you can select which profile you want to configure using the query profile selector at the top of the Relevance page: ![Query profiles dropdown on the Core Settings > Relevance page](https://mintcdn.com/lucidworks/FtDps0vG_MOhPC6g/assets/images/lw-platform/core-settings/core-settings-relevance-query-profiles.png?fit=max\&auto=format\&n=FtDps0vG_MOhPC6g\&q=85\&s=665543fc24f59880ff98a15f1b2ebbfa) Query profiles enable you to manage multiple search experiences within a single site. Each query profile represents a distinct search configuration, including a query pipeline and collection. > [!NOTE] > > The query profile selector only appears when your site has multiple query profiles configured. > If you have a single query profile, the selector is hidden and all settings apply to that profile automatically. You can create and manage query profiles in [Lucidworks Search](/docs/lucidworks-search/05-move-data-out/query-profile/overview) or [self-hosted Fusion](/docs/5/fusion/getting-data-out/query-basics/query-pipelines/query-profiles), or by contacting Lucidworks. > [!WARNING] > > If two query profiles point to the same query pipeline, changes made to one query profile's Core Settings will impact the other. ## Neural Hybrid Search Lucidworks Core Settings includes the option of using Neural Hybrid Search (NHS) to take advantage of advanced searching capabilities that combine lexical search and semantic search, enabling exact and partial keyword matching, phrase detection, and search results that understand the natural language users might enter in the search box. To improve the relevance of results, you can also set values to assess how closely results match and number of results returned. ![NHS settings options](https://mintcdn.com/lucidworks/FtDps0vG_MOhPC6g/assets/images/lw-platform/sites/sites-nhs.png?fit=max\&auto=format\&n=FtDps0vG_MOhPC6g\&q=85\&s=b916b7baf20218ecb6fbb21b482d972a) > **Weight balance between lexical and semantic search** > > Use the **Weight** slider to decide the relative importance of lexical (Lexical search is the basic type of search that uses exact matching of keywords to return results. > It is useful for situations where the results are simple and predictable, or when a keyword always returns what the user is trying to find. Lexical search can be a good solution for smaller datasets that are well-organized but struggles when the wording of the query is not exact or with common keywords.) and semantic (Semantic search understands the meaning behind the words used in a query and can compare the relationship of the query to the conceptual representation of items in a dataset to return more relevant results. With semantic search, exact keyword matches are not needed, giving the user more freedom in how they word their searches. An additional benefit of semantic search is the ability to return related results, even if those results do not include the keyword entered by the user.) search for your search results. As you increase the weighting of one type of search, the weight of the other type of search decreases. > > Depending on the type of content you have, you can adjust the slider to accommodate the information you want the user to see. > > For example, a legal, medical, or financial website might have industry-specific words that benefit from a more lexical approach, while an e-commerce website might want to show users similar products and will benefit from giving a greater weighting to semantic search. > > NHS uses both of these to optimize the search experience. > > **Fine tune the results** > > To improve results, evaluate the specific needs of your use case to determine the appropriate balance between lexical and semantic search. > > Begin testing by starting in the middle with 50% lexical and 50% semantic and perform a series of queries. > If the results do not match your expectations, then adjust the slider. > > **B2C** > > In a B2C context such as a grocery store chain, if a user searches for "ice cream" and the results prioritize "bag of ice" and "sour cream," the semantic weight should be increased. This helps return contextually relevant items like "waffle cones" and "chocolate syrup" that align with the shopper’s intent. > > **Financial services** > > In contrast, on a financial services site where a user is researching "bonds," overly broad results like CDs, mutual funds, or ETFs may dilute relevance. Increasing the lexical weight ensures the top results remain focused on bonds. > > Adjust the weighting strategy to match user intent and the goals of your business. > > Adjust the weights for your specific use case, and validate that the search results become more relevant for the users. > **Control how closely records match and the number of records returned** > > Two settings determine the number of records returned: > > * **Vector Similarity Threshold**: This threshold sets the minimum of how closely a document must match your query's meaning to be included in results. Enter a decimal value between `0` and `1`. > > * A higher minimum value returns only results that strongly match the query's meaning. Assessing possible matches to return strong results may increase latency (processing response time). > > * A lower minimum value returns more results because results do not have to match the query's meaning as closely. > > * Results that are not semantically close enough to the query's meaning are filtered out before results are re-ranked. > * **Vector Result Count**: This value specifies how many candidate results the vector (semantic) search retrieves before the results are merged and re-ranked with the lexical results. Enter an integer between `0` and `2000`. > > * A higher value assesses more semantic candidate results, which improves relevant results, but may increase latency (processing response time). > > * A lower value assesses fewer semantic candidate results, which may decrease relevant results, but also takes less processing time. > > > [!NOTE] > > > > These fields map to the `Min Return Vector Similarity` and `Number of Vector Results` fields in the Neural Hybrid Query stage settings. > > **Recommended starting values by use case** > > Use these starting values as a baseline, then adjust based on observed results. > > **B2B catalog** > > B2B catalog search involves dense product catalogs with technical terminology. > Users expect both precision (correct part or product) and coverage (all relevant variants). > > | Setting | Starting value | > | - | - | > | Vector Result Count | 75–150 | > | Vector Similarity Threshold | 0.60–0.70 | > > This balanced configuration provides a candidate pool wide enough to capture product variants and related SKUs, > while filtering results with weak semantic relevance. > > **Signs you should adjust:** > > * If searches return too many unrelated items, raise the threshold. > * If variant products are missing from results, lower the threshold or increase the result count. > > **E-commerce** > > E-commerce search benefits from high precision. > Shoppers expect results that closely match their query, and irrelevant results reduce conversion. > > | Setting | Starting value | > | - | - | > | Vector Result Count | 50–100 | > | Vector Similarity Threshold | 0.65–0.75 | > > The higher threshold filters weakly related products before re-ranking. > A moderate result count keeps latency low while giving the re-ranker enough candidates to work with. > > **Signs you should adjust:** > > * If facet-filtered result sets are unexpectedly sparse, lower the threshold toward `0.60` or increase the result count. > * If results feel unrelated to the query, raise the threshold toward `0.75–0.80`. > > **Knowledge management** > > Knowledge management and enterprise document search prioritize recall. > Users need to find the right document even when their wording differs from the document's language. > A threshold that is too strict hides relevant content. > > | Setting | Starting value | > | - | - | > | Vector Result Count | 100–200 | > | Vector Similarity Threshold | 0.50–0.60 | > > The larger candidate pool and lower threshold keep vector search broad enough to surface documents > that match query intent even when wording diverges significantly. > This is especially important for long-tail queries and specialized terminology. > > **Signs you should adjust:** > > * If results feel noisy or unrelated, raise the threshold in increments of `0.05` and re-evaluate. > * If users report missing documents, lower the threshold or increase the result count. > > **Tuning these settings** > > Adjust one setting at a time so you can identify what is causing changes in results. > > 1. **Start permissive.** Set Vector Result Count to `100–150` and Vector Similarity Threshold to `0.50`. > This gives you a broad candidate pool and avoids prematurely hiding relevant results. > > 2. **Adjust the threshold first.** The similarity threshold has the most direct impact on result quality. > Raise it gradually in increments of `0.05`, querying representative terms after each change. > > 3. **Tighten the result count last.** Once the threshold produces clean results, reduce Vector Result Count to improve response time. > Watch for result quality changes as you lower it — if results degrade, the count is too low for your collection size. > > > [!TIP] > > > > The underlying vector search algorithm (HNSW) is approximate. > > A higher Vector Result Count gives the algorithm more candidates to find the best matches, > > which is why starting high and narrowing down produces better outcomes than starting low. > > **What to watch for** > > * **Zero or very few results**: A threshold that is too high can exclude all vector candidates for some queries, causing NHS to fall back to lexical-only results. > A threshold of `0.80` or higher is rarely appropriate except for tightly controlled, well-structured catalogs. > If users report missing results, lower the threshold by `0.05–0.10` and test again. > * **Noisy or unrelated results**: If results don't feel related to the query, the threshold is likely too low. > Also check whether Vector Result Count is higher than needed — a large candidate pool with a low threshold gives re-ranking more noise to contend with. > * **Slow query response times**: Vector Result Count directly affects how many candidates are retrieved. > If query times are slow, reduce the result count in increments of `25`. > Note that if your collection spans multiple Solr shards, the effective candidate pool is Vector Result Count × shard count. > > For advanced pipeline-level configuration of these parameters, see the links applicable to your product: > > * Self-hosted Fusion clients, see [Choosing, implementing, and troubleshooting NHS stages](/docs/5/fusion/hybrid-search/hybrid-stage-differences) and [Semantic vector search test guidelines](/docs/5/fusion/hybrid-search/testing-svs). > > * Lucidworks Search clients, see [Choosing, implementing, and troubleshooting NHS stages](/docs/lucidworks-search/11-vector-search/hybrid-stage-differences) and [Semantic vector search test guidelines](/docs/lucidworks-search/11-vector-search/testing-svs). ## Sort Sort is how search results are ordered and can be set according to relevance, which is the degree to which each item matches a user’s query based on search settings. You can change the default sorting order that is used for results by arranging the tiles in the Sort section. This lets you sort first by relevance, then by date for items with identical relevance, or sort first by date, then by relevance for items with identical dates. ![description](https://mintcdn.com/lucidworks/g1p2ZULuslqrEkMX/assets/images/lw-platform/sites/sites-sort.png?fit=max\&auto=format\&n=g1p2ZULuslqrEkMX\&q=85\&s=ee7424ed5db71db9a76be031ef88fbf7) # Typeahead Source: https://doc.lucidworks.com/docs/lw-platform/lw-core/sites-typeahead Core Settings [localhost link]: http://localhost:3000/docs/lw-platform/lw-core/sites-typeahead [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-core/sites-typeahead [old doc.lw link]: https://doc.lucidworks.com/lw-platform/core/1gkhuh The Typeahead feature in Lucidworks Platform Core Settings provides real-time query and phrase suggestions as a user types into a search bar. This function helps users find relevant results faster by predicting what they are trying to search. As the user enters text into the search box, the system predicts possible queries and displays instant suggestions in a dropdown menu. The suggestions refine dynamically when the user enters more characters. When the user clicks on the suggestion, the product or document displays. > [!NOTE] > > Typeahead results returned by the API are sorted alphabetically. Sort options are not currently available. > **[Core Settings Typeahead](https://academy.lucidworks.com/training/019e4691-6560-7890-82e2-894bab6f364d/overview)** > > Learn how to configure and manage Typeahead suggestions in Core Settings to help users find relevant results faster. ## How suggestions are created Suggestions are created in two different ways: * **Custom terms**. You can enter typeahead suggestions for products and documents. In addition to suggestions you want to include and display when a user searches, you can also enter suggestions to exclude that are not relevant. Excluding suggestions that are not relevant can enhance your user's search experience as much as including suggestions that steer the user to the products or knowledge they seek. A maximum of 4,000 custom terms (included and excluded) can be entered. * **Suggested terms**. Every hour, Lucidworks Platform analyzes your customers' most frequent queries using signals from the [Signals Beacon](/docs/lw-platform/lw-analytics/signals/signals-beacon) or [Signals API](/docs/lw-platform/lw-analytics/signals/signals-api). The top 1,000 terms from the last 7 days are automatically added to your Included Typeahead Suggestions list. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio Click your use case below to see examples of how typeahead suggestions can enhance the search experience: **Business-to-Consumer** For a plumbing company, examples of Included typeahead terms are: * black bathroom faucet * gold bathroom faucet * return policy * clearance Examples of Excluded typeahead terms are: * shower curtain * bath towels * shower slippers **Business-to-Business** For an auto parts manufacturer, examples of Included typeahead terms are: * brake kits * carburetor calibration manual * OEM factory service manuals (FSMs) Examples of Excluded typeahead terms are: * single unit * retail price * body shops **Knowledge Management** For human resource knowledge management, examples of Included typeahead terms are: * benefits guide * company holidays * sick leave policy Examples of Excluded typeahead terms are: * employee address list * handbook * policy ## View suggestions The Typeahead screen displays tabs that contain Included and Excluded suggestions. ![Core Settings Typeahead screen](https://mintcdn.com/lucidworks/I-UkBChMQ01LqHmn/assets/images/lw-platform/sites/core-settings-typeahead-main.png?fit=max\&auto=format\&n=I-UkBChMQ01LqHmn\&q=85\&s=0f6da2e2472697b58ed6c655bdeb58a7) You can perform the following actions to review or configure how the suggestions display: * To view suggestions that contain certain characters, enter those characters in the **Search term** field and press **Enter**. * To display suggestions based on persistence status, user who last updated the suggestion, or the date the suggestion was created, click **Filters** and select or enter the criteria. **What is persistent?** A suggestion marked as "persistent" means that terms generated hourly do not overwrite that suggested term. All custom typeahead terms are persistent, and must be manually excluded or deleted to be removed from the Included table. To ensure that signal-based Typeahead terms are not replaced during the hourly refresh, toggle `Persistent` to `on`. **Last Edited (Updated) By value** The suggestions you enter manually in the user interface are called "custom" terms, with a value of the user signed on in the **Last Edited (Updated) By** field. The suggestions gleaned from customer queries are called "suggested" terms, with a value of **Lucidworks** in the **Last Edited (Updated) By** field. ![Core Settings Typeahead Filters](https://mintcdn.com/lucidworks/I-UkBChMQ01LqHmn/assets/images/lw-platform/sites/core-settings-typeahead-filters.png?fit=max\&auto=format\&n=I-UkBChMQ01LqHmn\&q=85\&s=c9cc17bed00a9e7db5dd4f8a44ce2265) * To set the options and columns that display on the Typehead screen, click **Table Settings** and select the toggle to turn the option on or off. ![Core Settings Typeahead Table Settings](https://mintcdn.com/lucidworks/I-UkBChMQ01LqHmn/assets/images/lw-platform/sites/core-settings-typeahead-table-settings.png?fit=max\&auto=format\&n=I-UkBChMQ01LqHmn\&q=85\&s=9bfc00a419db265759e4c374a60e1b30) ## Configure suggestions This section details the steps to configure and manage typeahead suggestions. ### Configure Included suggestions > **Configure individual Included Typeahead suggestions** > > To configure a single Included typeahead suggestion, complete the following actions: > > * To add an entry, access the Typeahead screen and click **Included > +Add**. Enter the term and press **Enter**. Then, click **Publish** to activate the changes on your site. > > * To edit an existing entry, click the entry, enter the changes, and then, click **Publish** to activate the changes on your site. > > > [!NOTE] > > > > All custom typeahead terms are persistent, and must be manually excluded or deleted to be removed from the Included table. To ensure that signal-based Typeahead terms are not replaced during the hourly refresh, toggle `Persistent` to `on`. > > **Other actions to manage individual suggestions** > > **Discard changes** > > To discard edits to an existing entry, select the entry and click **Discard**. > > **Delete suggestions** > > You can delete custom terms and suggested terms. > > > [!WARNING] > > > > When you publish the deletion of a suggested term generated from signals, the term moves to the **Excluded** list instead of being deleted. > > To stop a signal-generated term from appearing, use **Exclude**. > > To let the term be suggested again, delete it from the **Excluded** list. > > To delete an entry, hold the pointer over the entry and click the trash icon. > > When you confirm the deletion, the entry displays in a soft delete status. > > To finalize the deletion, click **Publish**. > > > [!NOTE] > > > > If you do not click **Publish**, the soft delete status is removed when you refresh the screen, and the entry is restored to the list. > > **Move included suggestions to the excluded list** > > To move a custom term you entered or a suggested term generated from signals from the **Included** list to the **Excluded** list, hold the pointer over the entry and click the **Exclude** icon. > > > [!NOTE] > > > > If you move a suggested term to the Excluded list, the system will not generate that suggestion again, regardless of how many signals contain that term. > > When you confirm the exclusion, the entry display in a soft exclude status. > > To finalize the move to the Excluded list, click **Publish**. > > > [!NOTE] > > > > If you do not click **Publish**, the soft exclude status is removed when you refresh the screen, and the entry is restored to the Included list. > **Edit multiple Included Typeahead suggestions** > > To edit more than one Included typeahead suggestion at a time, complete the following steps: > > In the Typeahead screen, hold the pointer over each entry you want to select and click the checkbox. To deselect all of the entries you have selected, click **Deselect**. > > > [!NOTE] > > > > To select all of the entries, hold the pointer over the **Terms** header and select the checkbox. All of the suggestions are selected. > > ![Core Settings Typeahead edit multiple entries](https://mintcdn.com/lucidworks/I-UkBChMQ01LqHmn/assets/images/lw-platform/sites/core-settings-typeahead-multiple-entries.png?fit=max\&auto=format\&n=I-UkBChMQ01LqHmn\&q=85\&s=99bb816ffa267f40b2686a7e02a5c995) > > The following sections detail how to exclude, delete, or deselect the selected entries. > > **Move included suggestions to the excluded list** > > To move the selected entries from the **Included** list to the **Excluded** list, click **Exclude**. > > > [!NOTE] > > > > If you move a suggested term to the Excluded list, the system will not generate that suggestion again, regardless of how many signals contain that term. > > When you confirm the exclusion, the entries display in a soft exclude status. > > To finalize the move to the Excluded list, click **Publish**. > > > [!NOTE] > > > > If you do not click **Publish**, the soft exclude status is removed when you refresh the screen, and the entries are restored to the Included list. > > **Delete multiple Included suggestions** > > To delete the selected entries, click **Delete**. > > > [!WARNING] > > > > When you publish the deletion, suggested terms generated from signals move to the **Excluded** list instead of being deleted. > > To stop signal-generated terms from appearing, use **Exclude**. > > To let a term be suggested again, delete it from the **Excluded** list. > > When you confirm the deletion, the entries display in a soft delete status. > > To finalize the deletion, click **Publish**. > > > [!NOTE] > > > > If you do not click **Publish**, the soft delete status is removed when you refresh the screen, and the entries are restored to the Included list. ### Configure Excluded suggestions Excluding a term blocks the term and related terms from being suggested. For example, if you exclude "dog", the terms "dog house" and "dog food" are also excluded, but "doghouse" is not excluded. You might want to exclude certain keywords from typeahead for several reasons: * Frequently searched terms, such as "sale," might dominate typeahead if not excluded, reducing variety in suggestions. * Filter out generic terms such as "info" or "product" that provide little user intent and might not help guide the user to meaningful content. * Exclude typeahead suggestions that do not support business goals, such as low-value queries or terms that distract from high-intent, conversion-focused results. ![Core Settings Typeahead screen](https://mintcdn.com/lucidworks/I-UkBChMQ01LqHmn/assets/images/lw-platform/sites/core-settings-typeahead-excluded.png?fit=max\&auto=format\&n=I-UkBChMQ01LqHmn\&q=85\&s=f86f53921b432dec61f0b220edc1c0a2) To manage Excluded typeahead suggestions: The only actions you can perform on the Excluded list are to add or delete entries. Suggested terms generated from signals that you delete from the **Included** list also display here. You cannot move excluded items to the Included list. To change a term from Excluded to Included, you must delete it from the Excluded list and then add it to the Included list. > **Configure individual Excluded Typeahead suggestions** > > To configure a single Excluded typeahead suggestion, complete the following steps: > > In the Typeahead screen, click **Excluded > +Add**. Enter the term and press **Enter**. Then click **Publish** to activate that term for use on your site. > > **Other actions to manage individual suggestions** > > **Discard changes** > > To discard edits to an existing entry, select the entry and click **Discard**. > > **Delete suggestions** > > To delete an entry, hold the pointer over the entry and click the trash icon. > > When you confirm the deletion, the entry displays in a soft delete status. > > To finalize the deletion, click **Publish**. > > > [!NOTE] > > > > If you do not click **Publish**, the soft delete status is removed when you refresh the screen, and the entry is restored to the list. > **Edit multiple Excluded Typeahead suggestions** > > To edit more than one Excluded typeahead suggestion at a time, complete the following steps: > > In the Typeahead screen, hold the pointer over each entry you want to select and click the checkbox. To deselect all of the entries you have selected, click **Deselect**. > > > [!NOTE] > > > > To select all of the entries, hold the pointer over the **Terms** header and select the checkbox. All of the suggestions are selected. > > ![Core Settings Typeahead edit multiple excluded entries](https://mintcdn.com/lucidworks/I-UkBChMQ01LqHmn/assets/images/lw-platform/sites/core-settings-typeahead-excluded-multiple.png?fit=max\&auto=format\&n=I-UkBChMQ01LqHmn\&q=85\&s=806b854bf6a7527e59bb440e5d86deb4) > > The following section details how to delete the selected entries. > > **Delete suggestions** > > To delete multiple entries, hold the pointer over each entry, click the checkbox, and then click **Delete**. > > When you confirm the deletion, the entries display in a soft delete status. > > To finalize the deletion, click **Publish**. > > > [!NOTE] > > > > If you do not click **Publish**, the soft delete status is removed when you refresh the screen, and the entries are restored to the list. # Typeahead Service API Source: https://doc.lucidworks.com/docs/lw-platform/lw-core/typeahead-api The Lucidworks Typeahead Service API returns a list of suggestions created in Lucidworks Platform Core Settings. Using the unique `TYPEAHEAD_ID` for your Typeahead configuration, you can retrieve a list of suggestions based on the characters included in the request. > [!NOTE] > > For detailed API specifications in Swagger/OpenAPI format, see [Platform APIs](/api-reference/get-typeahead-suggestions). > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Prerequisites To use this API, you need: * Typeahead suggestions entered or written into Lucidworks Platform Core Settings. A total of 5,000 suggestions are allowed in the following distribution: * Your organization can enter a maximum of 4,000 custom terms (included and excluded) in the Core Settings Typeahead user interface. * Every hour, a maximum of 1,000 of the terms entered most often in customer searches are added to the Included typeahead suggestions list. * The unique `TYPEAHEAD_ID` for your typeahead implementation. Contact your Lucidworks Platform representative for this information. ## Unique values for the typeahead use case Some query parameters unique to the `typeahead` use case can be used in the URL of the `GET` request of the Core Settings Typeahead Service API, including `prefix` and `limit`. Refer to the [API spec](/api-reference/get-typeahead-suggestions) for more information. ### Example GET request with `prefix` query parameter ```bash wrap Request theme={"dark"} curl --request GET \ --url https://{TYPEAHEAD_ID}.typeahead.lucidworks.com/typeahead/suggestions?prefix=El \ --header 'Accept: application/json' \ --header 'Authorization: Embed EMBED_TOKEN' \ --header 'Content-type: application/json' \ --data '' ``` #### Response The API call returns suggestions that begins with the letters `El`. ```json wrap theme={"dark"} [ "Elastic", "Electric", "Electrical", "Electronics", "Elegant", "Element", "Elevator", "Elite", "Elixir", "Ellipse" ] ``` ## Result sorting Typeahead results are sorted alphabetically. Sort options are not currently available with the API. > [!NOTE] > > If the request does not include a query parameter after the `?` in the URL of the request, the complete list of suggestions is returned. # AI Ranking Insights Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cs-ai-ranking-insights > **Key questions to get you started** > > Powered by Lucidworks Agent Studio AI Ranking Insights is a Commerce Studio feature that displays a clear, business-friendly explanation about why a product or content is ranked in a given position. This feature uses a large language model (LLM) to interpret primary ranking drivers, such as text relevance, rules, boosts, rewrites, and AI-driven signals like Neural Hybrid Search (NHS), in Fusion's debug response. ## AI Ranking Insights example To display the information, hold the pointer over a search result and select **Click Details**. In the Product Details section, click **AI Ranking Insights**. The AI ranking insights feature identifies key relevancy influencers including merchandising rules, matching fields, and matching logic, and then returns the reasoning in a readable format so merchandisers and search managers can quickly identify the key factors influencing a search result's relevancy. In this example, the AI ranking insight explains that the selected search result is ranked first because of a pin rule (listed in the **Execute** section of the Editor screen), and that the rule places the item above all other items. Merchandisers and other personnel would use this information to modify the factors of this and other search results, if needed, to rank other results higher than the bathroom faucet handle. ![AI Ranking Insights example](https://mintcdn.com/lucidworks/crYyCBOVRz4Fzz-B/assets/images/lw-platform/commerce-studio/lw-cs-ai-ranking-insight1.png?fit=max\&auto=format\&n=crYyCBOVRz4Fzz-B\&q=85\&s=c7462201c4575a6bb03ba5731c314dd2) AI Ranking Insights for a popular bathroom faucet handle ## Benefits Merchandisers, search managers, and other personnel can use this concise explanation to: * More quickly refine and optimize relevance without requiring expertise in Fusion configuration or search engineering. * Reduce the requirement for technical expertise to decipher raw scores, weights, and pipeline calculations. * Reduce reliance on engineering resources to troubleshoot relevance issues. * Reduce the risk of time-consuming, trial-and-error rule and other configuration changes. ## How it works This is the flow to display AI Ranking Insights for a product: 1. In Commerce Studio Editor, a user searches for a product. For example, bathroom faucet. 2. Lucidworks Platform captures the corresponding Fusion debug response in the Query Workbench. 3. The debug response, aware of the query context, rules, rewrites, and AI signals, is sent to an LLM. 4. The LLM returns a clear, concise explanation that takes the primary ranking factors into account: * Interaction of related rules, boosts, and relevance * Why the product displays in relation to the other products ## Technical requirements Because AI Ranking Insights reads the Fusion debug response, you must configure the query pipeline to include debug and explain data in every Commerce Studio query. Commerce Studio cannot pass query parameters per request, so this must be set at the pipeline level using following stage for the product you have deployed: * [Fusion Additional Query Parameters stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/set-query-params-stage#query-pipeline-stage-condition-examples) * [Lucidworks Search Additional Query Parameters](/docs/lucidworks-search/09-developer-documentation/config-specs/query-pipeline-stages/additional-query-parameters#query-pipeline-stage-condition-examples) To enable debug output for Commerce Studio: 1. In the Fusion UI, open the query pipeline used by your Commerce Studio application. 2. In the stage's **Condition** field, add the following expression to scope debug output exclusively to Commerce Studio queries: ```js theme={"dark"} request.hasParam("lw.em.queryType") ``` This ensures explain data is only added for Commerce Studio requests and not returned to other consumers of the same pipeline. 3. Add an **Additional Query Parameters** stage with the following parameter: | Name | Value | Policy | | - | - | - | | `debug` | `true` | `default` | Use `default` policy so the parameter is added only when not already set by the request. Use `replace` if you need to force debug output regardless of incoming request parameters. ![Additional Query Parameters enable debug output](https://mintcdn.com/lucidworks/ll8BxSz2UMFgmd8f/assets/images/lw-platform/commerce-studio/lw-cs-ai-ranking-insights-technical-req.png?fit=max\&auto=format\&n=ll8BxSz2UMFgmd8f\&q=85\&s=ea18ab8087d635ed1f267da122ba7116) Additional Query Parameters 4. Save the changes. **Debug response** The debug response includes Solr's `explain` data, which shows how each document's score was calculated — including contributions from lexical scoring, vector similarity, boosts, and merchandising rules. This is the data the LLM reads to generate the AI Ranking Insights explanation. For details about reading Solr explain output, including how to find it in Query Workbench and how to interpret NHS scoring, see the information for your product: * [Fusion Use Solr explain](/docs/5/fusion/hybrid-search/hybrid-stage-differences#use-solr-explain) * [Lucidworks Search Use Solr explain](/docs/lucidworks-search/11-vector-search/hybrid-stage-differences#use-solr-explain) # Migration guide Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cs-migrate This guide explains the client tasks required to migrate from Predictive Merchandiser to Commerce Studio in Lucidworks Platform. > [!NOTE] > > See [Commerce Studio versus Predictive Merchandiser](/docs/lw-platform/lw-cs/cstudio-versus-pm) for a feature comparison. While Lucidworks will complete the majority of the migration, you will need to perform certain pre-migration and post-migration tasks. The migration is one-way. The migration can be reverted back to Predictive Merchandiser, but any changes made in Commerce Studio are not reverted back into Predictive Merchandiser. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Prepare for the migration Complete these client tasks before Lucidworks begins the migration. > **Prepare Predictive Merchandiser for migration** > > ### Determine which rules and rewrites will be migrated > > > [!NOTE] > > > > * **Unpublished** rules or rewrites have never been published. > > > > * **Staged** rules or rewrites have been published at least once, but then were changed and those changes are not yet published. It also includes rules and rewrites that were deleted, but the deletion has not yet been published. > > #### Unpublished rules > > If you want unpublished rules migrated, then inform Lucidworks to set `excludeUnpublishedRules` to `false` during the migration. This is the default option. If you do not want unpublished rules to be migrated, tell Lucidworks to set `excludeUnpublishedRules` to `true`. > > #### Unpublished rewrites > > If you want unpublished rewrites migrated, then inform Lucidworks to set `excludeUnpublishedRewrites` to `false` during the migration. This is the default option. If you do not want unpublished rules to be migrated, tell Lucidworks to set `excludeUnpublishedRewrites` to `true`. > > #### Publish only approved content > > By default, migrated rules and rewrites are published in Commerce Studio if they are published in Predictive Merchandiser. > > If you want only approved rewrites and rules to be migrated as published, then inform Lucidworks to set `publishApprovedOnly` to `true` during the migration. > > #### Skip rules or rewrites > > If you want to skip all rules, then inform Lucidworks to set `skipRules` or `skipRewrites` to `true` during the migration. > > #### Staged rules and rewrites > > Staged rules and rewrites are skipped in the migration, so you must publish or revert all staged changes to rules and rewrites. > > You can only view staged changes in Predictive Merchandiser that belong to your user. > > To check for staged changes that belong to other users in your organization, do the following: > > 1. Copy the `precheck.sh` script below to check for staged (unpublished) rules and rewrites: > > ```bash expandable theme={"dark"} > #!/bin/bash > > set -e > > # Function to perform curl requests with error handling and retries > perform_curl_request() { > local url=$1 > local max_retries=3 > local retry_count=0 > local wait_time=5 > local curl_opts="-s -w '\n%{http_code}' -H 'Accept: application/json' -u '$FUSION_USERNAME:$FUSION_PASSWORD'" > > while [ $retry_count -le $max_retries ]; do > # Execute curl and capture response with status code > local response=$(eval "curl $curl_opts '$url'") > local status_code=$(echo "$response" | tail -n1) > local body=$(echo "$response" | sed '$d') > > # Check if status code is in 2xx range > if [[ $status_code =~ ^2[0-9][0-9]$ ]]; then > echo "$body" > return 0 > else > # Report the error > echo "Error: HTTP request failed with status code $status_code" >&2 > echo "URL: $url" >&2 > > # If it's a 4xx error, don't retry > if [[ $status_code =~ ^4[0-9][0-9]$ ]]; then > echo "Client error. Not retrying." >&2 > exit 1 > fi > > # For other errors (5xx), retry if we haven't reached max retries > if [ $retry_count -lt $max_retries ]; then > retry_count=$((retry_count + 1)) > echo "Retrying in $wait_time seconds... (Attempt $retry_count of $max_retries)" >&2 > sleep $wait_time > else > echo "Maximum retries reached. Giving up." >&2 > exit 1 > fi > fi > done > > exit 1 > } > > # Function to validate JSON blob rules > validate_json_blob_rule() { > local doc="$1" > local doc_id="$2" > > local json_blob_s=$(echo "$doc" | jq -r '.json_blob_s // empty') > # Guard: Exit early if no json_blob_s field > [ -z "$json_blob_s" ] && return 0 > > # Decode base64 and validate JSON structure > local decoded_json=$(echo "$json_blob_s" | base64 -d 2>/dev/null || echo "") > # Guard: Exit early if decoding failed > [ -z "$decoded_json" ] && return 0 > > # Check if the decoded JSON is valid > if ! echo "$decoded_json" | jq empty 2>/dev/null; then > # Invalid JSON in blob > bad_json_blob_rule_ids+=("$doc_id") > echo "found JSON blob rule with invalid JSON: $doc_id" > > # Add this entry to our JSON structure for bad JSON blobs > local content_entry=$(jq -n --arg id "$doc_id" \ > --argjson content "$doc" \ > --arg decoded_content "$decoded_json" \ > '{ > "id": $id, > "ruleContent": $content, > "decodedJsonBlob": $decoded_content, > "error": "Invalid JSON syntax" > }') > > # Add this entry to the second problem (index 1) in our JSON structure > json_output=$(echo "$json_output" | jq --argjson entry "$content_entry" '.problems[1].content += [$entry]') > return 0 > fi > > # Valid JSON - now check if it's multiple objects > # A simple heuristic: if we can't parse it as a single JSON value, it's likely multiple objects > if echo "$decoded_json" | jq -e 'type' >/dev/null 2>&1; then > # Guard: Exit early if it's a valid single JSON object > return 0 > fi > > # This means jq couldn't parse it as a single value, likely multiple objects > bad_json_blob_rule_ids+=("$doc_id") > echo "found JSON blob rule with multiple objects: $doc_id" > > # Add this entry to our JSON structure for bad JSON blobs > local content_entry=$(jq -n --arg id "$doc_id" \ > --argjson content "$doc" \ > --arg decoded_content "$decoded_json" \ > '{ > "id": $id, > "ruleContent": $content, > "decodedJsonBlob": $decoded_content > }') > > # Add this entry to the second problem (index 1) in our JSON structure > json_output=$(echo "$json_output" | jq --argjson entry "$content_entry" '.problems[1].content += [$entry]') > } > > # Function to check for staged published rules > check_staged_published_rule() { > local doc="$1" > local doc_id="$2" > local deployed="$3" > > # Guard: Exit early if rule is deployed (not staged) > [ "$deployed" != "false" ] && return 0 > > # Check if the doc exists in the live rewrites collection > local live_url="$FUSION_BASE_URL/api/apps/$FUSION_APP_ID/query-rewrite/search?q=id:$doc_id&isLive=true&doc_type=rule&fl&rows=1&start=0" > echo "fetching live rule via $live_url" > local live_response=$(perform_curl_request "$live_url") > > # Check if we have any rules in the live response array > local live_docs_count=$(echo "$live_response" | jq -r '.response.docs | length') > > # Guard: Exit early if doc doesn't exist in live collection > [ "$live_docs_count" -eq 0 ] && return 0 > > # Found a published rule with staged changes > staged_published_rule_ids+=("$doc_id") > echo "found published rule with staged changes: $doc_id" > > # Extract the live doc from the response > local live_doc=$(echo "$live_response" | jq '.response.docs[0]') > > # Create a new entry for this rule with both staging and live content > local content_entry=$(jq -n --arg id "$doc_id" \ > --argjson staging "$doc" \ > --argjson live "$live_doc" \ > '{ > "id": $id, > "stagingContent": $staging, > "liveContent": $live > }') > > # Add this entry to our JSON structure > json_output=$(echo "$json_output" | jq --argjson entry "$content_entry" '.problems[0].content += [$entry]') > } > > # Function to display help message > show_help() { > echo "Usage: $0 [output_file]" > echo "Example: $0 admin password https://fusion.example.com MyFusionApp precheck_results.json" > echo "This script performs pre-checks for Fusion content before migration." > echo "Arguments:" > echo " fusion_username Fusion username" > echo " fusion_password Fusion password" > echo " fusion_base_url Base URL of the Fusion instance" > echo " fusion_app_id Application ID of the Fusion app to check" > echo " output_file (Optional) Output file to save results (default: precheck_results.json)" > } > > # Check if required arguments are provided > if [ "$#" -lt 4 ]; then > show_help > exit 1 > fi > > FUSION_USERNAME=$1 > FUSION_PASSWORD=$2 > FUSION_BASE_URL=$3 > FUSION_APP_ID=$4 > OUTPUT_FILE=${5:-precheck_results.json} > > # Input validation > if [ -z "$FUSION_USERNAME" ]; then > echo "Error: fusion_username is required" > show_help > exit 1 > fi > > if [ -z "$FUSION_PASSWORD" ]; then > echo "Error: fusion_password is required" > show_help > exit 1 > fi > > if [ -z "$FUSION_BASE_URL" ]; then > echo "Error: fusion_base_url is required" > show_help > exit 1 > fi > > if [ -z "$FUSION_APP_ID" ]; then > echo "Error: fusion_app_id ID is required" > show_help > exit 1 > fi > > # Check if jq is installed > if ! command -v jq &> /dev/null; then > echo "Error: jq command line tool is required but not installed. Please install jq and try again: https://jqlang.org/" > exit 1 > fi > > # Check if output file exists > if [ -f "$OUTPUT_FILE" ]; then > read -p "File $OUTPUT_FILE already exists. Overwrite? (y/n): " -n 1 -r > echo > if [[ ! $REPLY =~ ^[Yy]$ ]]; then > echo "Operation cancelled." > exit 1 > fi > fi > > # Ensure the output file is writeable > if ! touch "$OUTPUT_FILE" &> /dev/null; then > echo "Error: Output file $OUTPUT_FILE is not writeable. Check output path / permissions and try again." > exit 1 > fi > > # Initialize JSON structure > json_output='{ > "problems": [ > { > "problem": "Published rule with staged changes will be skipped during migration", > "fix": "Publish or revert the changes, or manually re-create the skipped content after migrating", > "content": [] > }, > { > "problem": "JSON blob rule contains multiple JSON objects instead of a single object", > "fix": "Update the JSON blob rule to contain only a single JSON object at the top level", > "content": [] > } > ] > }' > > # Initialize array to store staged published rule IDs > declare -a staged_published_rule_ids > > # Initialize array to store bad JSON blob rule IDs > declare -a bad_json_blob_rule_ids > > # Fetch query rewrite instances with pagination > start=0 > rows=10 > processed_docs=0 > > while true; do > page_url="$FUSION_BASE_URL/api/apps/$FUSION_APP_ID/query-rewrite/instances?sort=id+asc&doc_type=rule&rows=$rows&editSessionId=*&start=$start" > echo "fetching next page of rules via $page_url" > response=$(perform_curl_request "$page_url") > > # Check if we got an empty array, which means we're done paginating > array_length=$(echo "$response" | jq -r '. | length') > if [ "$array_length" -eq 0 ]; then > break > fi > > echo "Retrieved $array_length rules at offset $start" > > # Process each doc in the array > while read -r doc; do > doc_id=$(echo "$doc" | jq -r '.id') > deployed=$(echo "$doc" | jq -r '.deployed') > doc_type=$(echo "$doc" | jq -r '.type // empty') > > # Check for bad JSON blob rules > if [ "$doc_type" = "json_blob" ]; then > validate_json_blob_rule "$doc" "$doc_id" > fi > > # Check for staged published rules > check_staged_published_rule "$doc" "$doc_id" "$deployed" > > processed_docs=$((processed_docs + 1)) > done < <(echo "$response" | jq -c '.[]') > > # Move to the next page > start=$((start + rows)) > done > > # Write the final JSON output to file > echo "$json_output" | jq '.' > "$OUTPUT_FILE" > > # Output results > total_staged_issues=0 > total_json_blob_issues=0 > if [ -n "${staged_published_rule_ids[*]:-}" ]; then > total_staged_issues=${#staged_published_rule_ids[@]} > fi > if [ -n "${bad_json_blob_rule_ids[*]:-}" ]; then > total_json_blob_issues=${#bad_json_blob_rule_ids[@]} > fi > > total_issues=$((total_staged_issues + total_json_blob_issues)) > > # Guard: Exit early if no issues found > if [ $total_issues -eq 0 ]; then > echo "All pre-checks passed. No issues found." > echo "Processed $processed_docs rules." > exit 0 > fi > > # Report issues found > echo "The following pre-checks failed:" > > # Report staged published rule issues > if [ $total_staged_issues -gt 0 ]; then > echo " Found published rules with staged changes. Publish or revert the changes to fix this issue." > > # Display up to 10 IDs > display_count=$([ $total_staged_issues -gt 10 ] && echo 10 || echo $total_staged_issues) > for ((i=0; i echo " - ${staged_published_rule_ids[$i]}" > done > > # Indicate if there are more > [ $total_staged_issues -gt 10 ] && echo " ... and $((total_staged_issues - 10)) more." > fi > > # Report JSON blob rule issues > if [ $total_json_blob_issues -gt 0 ]; then > echo " Found JSON blob rules with multiple JSON objects instead of a single object." > > # Display up to 10 IDs > display_count=$([ $total_json_blob_issues -gt 10 ] && echo 10 || echo $total_json_blob_issues) > for ((i=0; i echo " - ${bad_json_blob_rule_ids[$i]}" > done > > # Indicate if there are more > [ $total_json_blob_issues -gt 10 ] && echo " ... and $((total_json_blob_issues - 10)) more." > fi > > echo "See $OUTPUT_FILE for the full list of invalid content with complete document details" > echo "Processed $processed_docs rules." > exit 0 > ``` > > 2. Run the script, replacing the placeholder values with your values. > > ```bash wrap theme={"dark"} > ./precheck.sh FUSION_USERNAME FUSION_PASSWORD FUSION_BASE_URL FUSION_APP_ID > ``` > **Placeholder definitions** > > | Placeholder | Description | > | - | - | > | `FUSION_USERNAME` | Your Fusion username. | > | `FUSION_PASSWORD` | The password for your Fusion user. | > | `FUSION_BASE_URL` | The URL of your Fusion instance including `https://`. For example, `https://FUSION_HOST.com`. | > | `FUSION_APP_ID` | The application ID of the Fusion app that contains your Predictive Merchandiser. This is the value of the `id` field, and may or may not match the `name` of the Fusion app. To obtain the ID, sign in to your Fusion instance. For example, `FUSION_INSTANCE.com`. Then also open a different browser window and enter `https://FUSION_INSTANCE.com/api/apps`. The `id` and `name` display for each valid Fusion app. The value in the `id` field is the value that needs to be used in this field. | > > > [!NOTE] > > > > If you receive an error stating `bash: ./precheck.sh: Permission denied`: 1. Make the script > > executable: `chmod +x precheck.sh`. 2. Run the script again. > > 3. Check the output to see if any issues were detected. If there are no issues, the output returns `All pre-checks passed. No issues found.` Continue to [retrieve list of objects in Predictive Merchandiser](#retrieve-lists-of-objects-in-predictive-merchandiser). If there are issues, the output returns a list of issues like the following: > > ``` > The following pre-checks failed: > Found published rules with staged changes. Publish or revert the changes to fix this issue. > - 2fRtM1GEsU > - E1YkUTX9r6 > - Eb2A6WARag > - FNS7Whciwx > - LlIsMfK4kq > - OidpIUrVv3 > - P39TDQ2X1K > - RYbY2XPMOI > - ZHvW2LiQpe > - aCseNzc4Xc > ... and 6 more. > See precheck_results.json for the full list of invalid content > ``` > > 4. Review `precheck_results.json` and inspect each reported rule. If you created the rules, sign into Predictive Merchandiser and publish or revert the staged changes. If the unpublished rules were created by a different user, you cannot publish or revert the rules in the Predictive Merchandiser UI. There are a few options for resolving unpublished rules owned by another user: > > * After you complete the pre-migration tasks, tell Lucidworks to proceed with the migration. These rules are skipped and you can re-create them in Commerce Studio. > * Use the Fusion [Query Rewrite](/api-reference/query-rewrite-api/get-the-query-rewrite-status) and [Custom Rule](/api-reference/custom-rule-type-api/get-a-custom-rule-type) APIs to manually publish or revert the unpublished rules. > * Use the Fusion [Query Rewrite](/api-reference/query-rewrite-api/get-the-query-rewrite-status) and [Custom Rule](/api-reference/custom-rule-type-api/get-a-custom-rule-type) APIs, or Solr, to manually change the edit session ID of the content in Solr to your current user. Then, manually fix the content in the Predictive Merchandiser UI. > * Have the user that owns the content in Predictive Merchandiser sign in and either publish or revert the changes. > > 5. After resolving issues, re-run the script. If there are no issues, continue to [retrieve list of objects in Predictive Merchandiser](#retrieve-lists-of-objects-in-predictive-merchandiser). > > > [!NOTE] > > > > You can run the precheck.sh script at any time, even after a migration if desired. It makes no > > changes to contents and works even if Commerce Studio is enabled. > **Retrieve lists of objects in Predictive Merchandiser** > > After preparing Predictive Merchandiser for migration, Lucidworks recommends that you export lists of rules, rewrites, templates, and zones from your Predictive Merchandiser instance to compare against Commerce Studio later. This will help serve as a reference when performing your post-migration validation checks. > > 1. Export a list of your rules and rewrites: > > ```bash theme={"dark"} > curl --request GET \ > --u USER:PASSWORD \ > --url 'https://FUSION_HOST/api/apps/APP_NAME/query-rewrite/instances' \ > --header 'accept: application/json' \ > > exported-rules.json > ``` > > 2. Create an inventory of your rules, noting how many of each type and tag appear in the list. > > 3. Export a list of your zones: > > ```bash theme={"dark"} > curl --request GET \ > -u USER:PASSWORD \ > --url 'https://FUSION_HOST/api/templating/zones?context=app:APP_NAME' \ > --header 'Accept: application/json' \ > > zones.json > ``` > > 4. Export a list of your templates: > > ```bash theme={"dark"} > curl --request GET \ > -u USER:PASSWORD \ > --url 'https://FUSION_HOST/api/templating/templates?context=app:APP_NAME' \ > --header 'Accept: application/json' \ > > templates.json > ``` > **Notify Lucidworks the migration can be executed** > > Notify Lucidworks to begin the migration, but keep in mind that once the migration begins, you will no longer be able to access Predictive Merchandiser. > > Lucidworks will set up the Commerce Studio integration and instance, and migrate your data from Predictive Merchandiser to Commerce Studio. > > > [!CAUTION] > > > > Do not proceed with subsequent procedures until Lucidworks confirms the migration is successful. ## Post-migration tasks Complete these client tasks when Lucidworks notifies you the migration is complete. > **Validate migration data** > > Lucidworks will run the validation checks in this section, but you must also validate that all Predictive Merchandiser objects appear in Commerce Studio. > > Because you can no longer access Predictive Merchandiser, you must consult the [exported JSON](#retrieve-lists-of-objects-in-predictive-merchandiser) you generated in **Retrieve lists of objects in Predictive Merchandiser** for validation checks. > > 1. Sign in to [Lucidworks Platform](https://platform.lucidworks.com) as a workspace owner and navigate to **Commerce Studio**. > 2. Navigate to **Rules**, then compare your rule count in Commerce Studio against the JSON you [exported from Predictive Merchandiser](#retrieve-lists-of-objects-in-predictive-merchandiser). > 3. Navigate to **Rewrite**, then validate that your query rewrites in Commerce Studio match the exported JSON. > 4. Navigate to **Settings**, then validate your templates have been correctly migrated. > 5. Open each page, then validate your Predictive Merchandiser zones have become sections in Commerce Studio, and they are associated with the correct page. > 6. Navigate to the **Editor** and check that rules and rewrites are applied as expected. Some rules and rewrites only fire under specific conditions: > 1. For rules that fire under specific templates, change your page to match the required template. > 2. For rules that fire only when specific tags are applied, verify the tags are displayed on the Rules page for the rule. > 7. Perform additional rules and rewrites validations as needed, using the exported rules JSON as a reference. For example, check that the direction of synonym rewrites matches the expected direction. > > If you encounter any issues, contact your Lucidworks representative. > > Web traffic continues to use rules and rewrites from Predictive Merchandiser. Changes made in Commerce Studio do not affect live traffic. Contact Lucidworks when you complete the validation tasks. ## Revert to Predictive Merchandiser If you want to revert back to using Predictive Merchandiser, inform Lucidworks. Then Lucidworks must delete the Commerce Studio instance. If the Commerce Studio instance is deleted, changes you made to Commerce Studio after the initial migration from Predictive Merchandiser are *not* populated back into Predictive Merchandiser. When the Commerce Studio instance is deleted, the system should automatically revert the Fusion app back to Predictive Merchandiser. This restores access to Predictive Merchandiser and routes live traffic back to its rules and rewrites, if traffic had previously been switched to Commerce Studio. ## Frequently asked questions **Can I revert to Predictive Merchandiser after switching to Commerce Studio?** Yes. However, any changes made in Commerce Studio after switching will *not* be reverted back into Predictive Merchandiser. **Does switching to Commerce Studio immediately affect live web traffic?** No. After a successful migration, web traffic continues to use rules and rewrites from Predictive Merchandiser. **What happens if I forget to publish changes in Predictive Merchandiser before migrating?** If you fail to publish pending rules and rewrites before starting the migration, the migration may fail or result in incomplete or inaccurate data. All changes must be published before proceeding. ## Troubleshooting This section provides troubleshooting steps for resolving issues with the Commerce Studio [Editor](/docs/lw-platform/lw-cs/cstudio-editor) when integrated with Fusion. Use this guidance to debug unexpected behavior that may be caused by Fusion query pipeline or query profile configuration. This content is intended for users with experience in Fusion and search engineering. ### Symptoms You may be experiencing a configuration issue if you observe any of the following: * No results or facets returned in the Editor * Error messages when performing searches * Rules not firing or not appearing after creation * Rewrites not triggering or not affecting live traffic * Mismatch between facets and results list * “Targeted documents” column in the rules table is empty or incorrect * No field value suggestions when configuring rule conditions * Missing stage data in the Ranking Factors UI ### General troubleshooting steps 1. Open your browser’s developer tools and go to the Network tab. 1. Retry the failing action. 2. Look for requests with a non-200 status or check `render` endpoint responses for `errorMessage` fields. 3. Use the `fusionRequestUrl` to replicate the request in Fusion Query Workbench. 2. Verify that the query pipeline behaves as expected in Fusion Query Workbench. 1. Confirm there are no errors. 2. Verify expected results are returned. 3. In the **JSON view**, check for `fusion.applicable_rules` or `fusion.tagger` values. 3. Confirm that rules and rewrites are saved to the correct Solr collections. 1. In Solr Admin, check `APP_NAME_query_rewrite_staging_em` and `APP_NAME_query_rewrite_em`. 2. Use the rule ID to query and confirm the entry exists. > [!WARNING] > > 1. Commerce Studio exclusively manages `APP_NAME_query_rewrite_staging_em` and `APP_NAME_query_rewrite_em`. Do not manually add, edit, or delete documents in these collections. > 2. Commerce Studio reflects rules stored in its own platform database. Deleting documents from these Fusion Solr collections does not delete the corresponding rules in Commerce Studio. The collections will re-sync the next time Commerce Studio writes rules. > 3. Custom tooling built against these collections is not supported. 4. Ensure the staging collection has only one replica. 1. If multiple replicas exist, set `shards.preference=replica.leader` in the **Apply Rules** and **Text Tagger** stage parameters. 5. Verify that the pipeline supports the `fl` parameter. 1. Do not overwrite `fl`. Add required fields only when needed. 2. Do not use `fl=*`. ### Required pipeline configuration Your Fusion query pipeline must include the following stages in this order: 1. **Text Tagger stage** with a blank value in the **Tagger Collection** field 2. **Apply Rules stage** with a blank value in the **Collection** field 3. **Solr Query stage** 4. **Modify Response stage** 5. **Response Diagnostics stage** In addition, the pipeline must: * Use the `edismax` query parser (`defType=edismax`) * Preserve the following query parameters: `tags`, `lw.rules.simulate`, `lw.app.emStatus`, `context`, `lw.tagger.debug`, `lw.rules.debug`, `lw.em.staging` * Preserve required response fields: `response.docs`, `response.numFound`, `fusion.tagger`, `fusion.applicable_rules`, `fusion.applicable_stages`, `response.facet_counts`, `responseHeader.params` ### Feature-specific checks #### Targeted document lookup * The Fusion app and query profile must have the same name. * The query profile must support `q=**:**` and standard `fq` parameters. * Avoid using grouping, collapse/expand, or custom logic that may interfere with standard filter behavior. #### Field value suggestions * The Solr collection must match the Fusion app name. * The collection must support the `/terms` request handler with standard parameters. * Suggestions will fail if `/terms` is missing or misconfigured. #### Rewrites and rules interaction * If the **Text Tagger** stage appears before the **Apply Rules** stage, rewrites apply first. * If the **Apply Rules** stage appears before the **Text Tagger** stage, only the original terms are used for rule evaluation. * Rules must target the rewritten query term, not the original term. #### Grouping via collapse/expand * The query pipeline must set an `fq` with the collapse field specified, indicating what field identifies members of a group. For example, set `fq={!collapse field=product_id_s}` when `expand=true` is passed as a query param. * Set the following query parameters: ```bash theme={"dark"} expand=true expand.rows=5 ``` * Relevant response fields include the following: ```bash theme={"dark"} expanded response.docs ``` #### Query Workbench debugging tips * Use the correct query profile and associated pipeline. * Set the following query parameters: ```bash theme={"dark"} lw.rules.debug=1 lw.tagger.debug=1 lw.em.staging=1=_query_rewrite_staging_em lw.app.emStatus=CONNECTED queryProfileID= tags= lw.rules.target_segment= ``` * Use **View As: JSON** to verify `fusion.applicable_rules` and the final query string. * Use custom JavaScript stages to inspect `ctx` or log intermediate values. ### Known configuration issues * Hardcoded `tags` in pipelines may prevent rules from matching if users forget to apply corresponding tags in the Editor. * Query pipelines that use grouping may break document targeting. Only collapse/expand-based grouping is supported. Grouping via Solr `group` params or blockjoin query parser is not supported. * If a boost stage and a rule both adjust relevancy, only one may take effect, depending on rule priority and creation date. # Rules and Rewrites API Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cs-rules-rewrites-api The Rules and Rewrites API for Commerce Studio enables you to create and manage merchandising [rules](/docs/lw-platform/lw-cs/cstudio-rules) and [query rewrites](/docs/lw-platform/lw-cs/cstudio-query-rewrite) programmatically. This API supports enterprise automation workflows, cross-environment synchronization, and integration with internal tools. For complete details about all of its endpoints, methods, and parameters, see the [Rules and Rewrites API reference](/api-reference/rule-management/list-rules). ## When to use this API The Rules and Rewrites API enables the following use cases: * **Automate rule deployment**: Create and update rules and rewrites through CI/CD (continuous integration/continuous deployment) pipelines or automated workflows. * **Synchronize across environments**: Maintain consistent rules and rewrites across development, QA (quality assurance), and production environments. * **Manage rules at scale**: Efficiently handle large rule sets that are impractical to manage through the UI (user interface) alone. * **Fallback with version control**: Fetch rules and rewrites, then commit them to your source control repository at intervals so you can easily revert to earlier versions if needed. * **Integrate with AI agents**: Use AI to automate creation and updates of rules and rewrites. > [!NOTE] > > For visual rule creation and management, use the Commerce Studio UI. > The API is designed for programmatic workflows where automation and integration are required. ## Key concepts ### Rule and rewrite identifiers Every rule and rewrite has two ID fields that you can use interchangeably in API operations: * **`id`**: Automatically generated UUID (Universally Unique Identifier) assigned by the platform when you create a rule or rewrite. This identifier is unique within the Commerce Studio instance. * **`externalId`**: Optional user-defined identifier that you can assign when creating a rule or rewrite. This field enables you to maintain your own naming conventions and synchronize rules across multiple environments. > [!TIP] > > Use external IDs to maintain stable references across environments. > For example, assign an external ID like `promo-summer-2026` to ensure the same rule can be identified and updated consistently in development, QA, and production. > [!WARNING] > > External IDs must be unique within a Commerce Studio instance. > The API prevents duplicate external IDs to maintain rule integrity. ### Authentication scopes The API uses three separate authentication scopes: * `commercestudio.rules`: Required for [rule](/docs/lw-platform/lw-cs/cstudio-rules) operations (create, read, update, delete rules) * `commercestudio.rewrites`: Required for [query rewrite](/docs/lw-platform/lw-cs/cstudio-query-rewrite) operations (create, read, update, delete rewrites) * `commercestudio.bulkoperations`: Required for [bulk operations](#bulk-operations) (publish, unpublish, edit, delete, and migrate operations on multiple rules) Request separate access tokens for each scope based on the operations you need to perform. ### Rate limiting Platform rate limits apply to all API requests to protect system stability. If you encounter rate limit errors, implement exponential backoff in your integration. ## Use the Rules and Rewrites API To use the API, you need a Lucidworks service account. Then you can gather your credentials and begin making API calls. For complete details about API endpoints, methods, and parameters, see the [Commerce Studio Rules and Rewrites API reference](/api-reference/rule-management/list-rules). > **Create a service account** > > If you don't already have a Lucidworks service account of type "API", complete the following steps: > > **Step 1** > > In Lucidworks Platform, go to **Settings** > **Service Accounts**. > > **Step 2** > > Click **Create New Service Account**. > > **Step 3** > > In the New Service Account window, be sure to select **API** as the service account type. > Enter a name and optionally a description to help you remember what this account is for. > > **Step 4** > > Click **Create New Service Account**. > The new account appears in the list. > Click the account you created to find the **Client ID** and **Client Secret** you need to access the API. > **Gather your credentials** > > You'll need the following information to access the API: > > * **Commerce Studio ID**: Your Commerce Studio instance identifier > * **Client ID**: From your service account > * **Client Secret**: From your service account > > **1. Find your Commerce Studio ID** > > Your Commerce Studio ID is part of your Commerce Studio URL. > For example, if your Commerce Studio URL is `https://COMMERCE_STUDIO_ID.experiencemanager.lucidworks.com`, your Commerce Studio ID is `COMMERCE_STUDIO_ID`. > > **2. Get your service account credentials** > > In Lucidworks Platform, go to **Settings** > **Service Accounts** and click the service account you created. > Copy the **Client ID** and **Client Secret**. > **Access the API** > > **1. Fetch an access token** > > Before making API requests, you need to authenticate and obtain an access token. > > Send a POST request to the authentication endpoint: > > ```bash theme={"dark"} > curl --request POST \ > --url 'https://identity.lucidworks.com/oauth2/ausao8uveaPmyhv0v357/v1/token?scope=API_SCOPE&grant_type=client_credentials' \ > --header 'Accept: application/json' \ > --header 'Authorization: Basic [CLIENT_ID:CLIENT_SECRET_BASE64]' \ > --header 'Cache-Control: no-cache' \ > --header 'Content-Type: application/x-www-form-urlencoded' > ``` > > Replace `API_SCOPE` with one or more of these (as a space-separated list): > > * `commercestudio.rules` for rule operations > * `commercestudio.rewrites` for query rewrite operations > * `commercestudio.bulkoperations` for bulk operations > > The `Authorization` header uses basic authentication with your base64-encoded client ID and client secret. > You can encode your credentials using: > > ```bash theme={"dark"} > echo -n "CLIENT_ID:CLIENT_SECRET" | base64 > ``` > > > [!NOTE] > > > > Some HTTP clients perform the base64 encoding automatically when you provide the client ID as the username and client secret as the password. > > A successful response returns: > > ```json theme={"dark"} > { > "token_type": "Bearer", > "expires_in": 3600, > "access_token": "YOUR_ACCESS_TOKEN", > "scope": "commercestudio.rules" > } > ``` > > **2. Make API requests** > > Use the access token in the `Authorization` header of your API requests: > > ```bash theme={"dark"} > curl --request GET \ > --url 'https://{COMMERCE_STUDIO_ID}.experiencemanager.lucidworks.com/em-rules' \ > --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' > ``` > > Replace `{COMMERCE_STUDIO_ID}` with your Commerce Studio instance ID. > > **3. Refresh your token** > > Access tokens expire after 60 minutes. > > > [!WARNING] > > > > Once you request a new token, the previous one is deleted *even if it has not yet expired*. > > All subsequent API calls must use the new token. ## Bulk operations Bulk operations enable you to perform actions on multiple rules simultaneously. This is useful for scenarios like these: * Publishing or unpublishing large sets of rules at once * Applying consistent edits across multiple rules * Deleting obsolete rules in batches * Migrating rule sets between Commerce Studio instances > [!NOTE] > > Bulk operations require an authentication token with the `commercestudio.bulkoperations` scope. > See [Authentication scopes](#authentication-scopes). ### Supported bulk operations The API supports these bulk operation types: * `publishRule`: Make multiple rules active simultaneously. * `unpublishRule`: Deactivate multiple rules at once. * `editRule`: Apply the same updates to multiple rules. * `deleteRule`: Remove multiple rules in one operation. * `migrateRule`: Copy rules to another Commerce Studio instance. ### Example requests Each bulk operation is a POST request to `/bulk-operations`. The request body's `type` field determines which operation runs, and you can target rules by ID, external ID, or a `specification` filter (or a combination of all three), as shown in these examples: **Publish** Publish all draft rules tagged `holiday-2026`. ```json theme={"dark"} { "type": "publishRule", "specification": { "tags": ["holiday-2026"], "publishState": "DRAFT" } } ``` **Unpublish** Unpublish a specific set of rules by ID. ```json theme={"dark"} { "type": "unpublishRule", "ruleIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "7c9e6679-7425-40de-944b-e07fc1f90ae7" ] } ``` **Edit** Raise the precedence of every rule tagged `holiday-2026`. This example sets `stageChanges` to `false`, so the patch applies immediately, including to already-published rules. Set `stageChanges` to `true` instead to apply the patch to staging content only, leaving published rules live and unaffected until the changes are published. ```json theme={"dark"} { "type": "editRule", "specification": { "tags": ["holiday-2026"] }, "patch": { "precedence": 5 }, "stageChanges": false } ``` **Delete** Delete draft rules last modified before a cutoff date, excluding one rule you want to keep. ```json theme={"dark"} { "type": "deleteRule", "specification": { "publishState": "DRAFT", "lastModifiedEnd": "2026-01-01T00:00:00Z" }, "excludeRuleIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } ``` **Migrate** Migrate a rule to another Commerce Studio instance and publish it there immediately. ```json theme={"dark"} { "type": "migrateRule", "ruleExternalIds": [ "promo-summer-2026" ], "targetExperienceManagerInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "published": true } ``` ### How bulk operations work Bulk operations execute asynchronously. When you create a bulk operation, the API returns immediately with an operation ID. You can then poll the operation status to track progress. **1. Create a bulk operation** Send a POST request to `/bulk-operations` with the operation type and list of rule IDs or external IDs. The API returns a bulk operation ID and initial status. **2. Monitor operation progress** Poll the bulk operation status using GET `/bulk-operations/{id}`. The response includes the following information: * Overall operation status: * `IN_PROGRESS`: Operation is currently executing. * `COMPLETED`: All rules processed successfully. * `FAILED`: Operation failed before processing any rules. * `COMPLETED_WITH_ERRORS`: Some rules succeeded, others failed. * Individual status for each rule * Error messages for any failed rules > [!WARNING] > > Rules included in an active bulk operation cannot be modified until the operation completes. > The `pendingInBulkOperation` field indicates when a rule is locked by a bulk operation. **3. Handle completion** When the operation reaches a terminal status (`COMPLETED`, `FAILED`, or `COMPLETED_WITH_ERRORS`), review the results. For operations that completed with errors, the response identifies which rules succeeded and which failed. For detailed information about bulk operation endpoints and parameters, see the [Bulk Operations API reference](/api-reference/bulk-operations/list-bulk-operations). ### Best practices Follow these guidelines when using bulk operations: * **Start with small batches**: Test bulk operations on a small set of rules before scaling up. * **Monitor operation status**: Don't assume success—always check the final status and handle partial failures. * **Handle errors gracefully**: When operations complete with errors, review which rules failed and retry them individually if needed. * **Avoid modifying locked rules**: Check the `pendingInBulkOperation` flag before attempting to update rules. * **Use external IDs for stability**: External IDs make it easier to retry operations and maintain consistency across environments. For detailed information about bulk operation endpoints and parameters, see the [Bulk Operations API reference](/api-reference/bulk-operations/list-bulk-operations). # Editor Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cstudio-editor The Commerce Studio Editor lets you configure search ranking rules, manage product boosting and blocking, set facets, and preview search results in real time to optimize product visibility. To access it, go to your site in Commerce Studio and click **Commerce Studio** > **Editor**. ![Home - Editor](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-home-editor.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=7743070b46b9c165e0784099f6426d83) > [!TIP] > > If the Editor doesn't display items in the expected format, you might need to configure Commerce Studio's [settings](/docs/lw-platform/lw-cs/cstudio-settings). > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Use the Conditions Manager At the top of the Editor you'll find the Conditions Manager. This is where you set the conditions for any rules you create in Commerce Studio, such as the query, timeframe, category, and more. The full page control displays in the Conditions Manager. To collapse the Conditions Manager, click the arrow below the Conditions Manager. ![Conditions Manager](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-conditions-manager.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=da768e74a19e3ee877562829e21b8031) ### Select a search profile to preview The Preview dropdown shows you the available search profiles. Query profiles represent different predefined search results that you can display on different pages of your customer-facing site, such as new items, seasonal items, sale items, and so on. You might also have experimental query pipelines for testing different configurations. ![Select a search profile from the Preview list](https://mintcdn.com/lucidworks/NXdmPj01VTcfSoKs/assets/images/lw-platform/commerce-studio/lw-cs-editor-query-profile-selector2.png?fit=max\&auto=format\&n=NXdmPj01VTcfSoKs\&q=85\&s=96d4a616dc3eed80e41fc48ae6c01a25) Select the search profile that represents the items you want to preview. ### Use search conditions When **Search** is selected in the Conditions Manager, you can enter queries and see the results in the live preview. ![Select Search to enter queries and preview the results.](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-editor-search-conditions2.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=f0afa13e720c3db09740b72e86bf3dd5) You can enter multiple queries that specify the qualifier for the search terms: * **is**: The search query must match the defined term exactly. For example, if the rule is set to "\[is] black shoes", it only triggers when the user search is exactly "black shoes." * **contains**: The search query must include one or more of the defined terms anywhere within the query. Each word is evaluated independently. For example, if the rule is set to "\[contains] black shoes", it triggers for any query containing "black" (such as "black boots") and any query containing "shoes" (such as "running shoes"). The words do not need to appear together or in a specific order. * **contains phrase**: The search query must include the defined phrase in the exact word order entered. For example, if the rule is set to "\[contains phrase] black shoes", it triggers for "black shoes" or "men's black shoes," but not for "shoes black" or "black running shoes." * **starts with**: The search query must begin with the defined word or phrase. For example, if the rule is set to "\[starts with] winter", it triggers for "winter jackets" or "winter boots," but not for "jackets for winter." Multi-word phrases respect word order, so "\[starts with] winter jackets" triggers for "winter jackets sale" but not for "jackets winter sale." * **ends with**: The search query must end with the defined word or phrase. For example, if the rule is set to "\[ends with] manual", it triggers for "installation manual" or "product manual," but not for "manual installation guide." Multi-word phrases respect word order, so "\[ends with] near me" triggers for "pizza near me" but not for "near pizza me." If you enter multiple queries, you can click to switch between them in the live preview. You can also filter results by tags, fields, or date range. ### Use category conditions The Category condition in the Conditions Manager impacts all of the following aspects of information simultaneously on the Commerce Studio Editor screen: * Live preview, which displays the results returned for a user on that category page * Rules (pin, boost, bury, redirects, and so on) created when the category is selected are saved and relate to that category, not to the entire site or in keyword searches * Individual search result metrics such as impressions, CTR, conversion, and so on, are filtered based on the specified category so merchandisers can identify the individual search result's performance The Category condition matches against the Solr field designated in the [Commerce Studio Settings **Category** field](/docs/lw-platform/lw-cs/cstudio-settings#configure-categories). When you select **Category** in the Conditions Manager, you can enter values as a live typeahead search for categories, then select one or more to affect the live preview, rules, and search metrics. Just like search conditions, you can enter more than one category, then click to switch between them to view the effect on search results. ![Select Category to search on specific categories.](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-category.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=0be56ec2d99e08c8afc9a88d952608a5) ## Configure the item card display The fields displayed in the Editor for any search profile are configured on the [Settings](/docs/lw-platform/lw-cs/cstudio-settings) screen. Once those are configured, you can click **Preview Settings** in the Editor to toggle whether each field is displayed or hidden, including these: * Item fields, such as the title, description, image, and so on. * Variants such as color or image variants * Metric fields such as impressions, add-to-cart (ATC), conversion rate (CVR), revenue per visit (RPV), and more. ![Preview settings](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-preview-settings1.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=df42311177417e01b59a63123b614126) ## View and modify rules In the Execute panel on the left side of the Editor, you can view the rules that apply to the current query or category. ![Rule state and preview setting](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-editor-view-rules.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=c64a0fb11723c425fa7ddb46736ce5a2) ### Rule state Published rules are indicated by an up arrow in the **State** column. Draft rules are displayed with a pencil icon in the **State** column. ### Preview rule The **Preview** feature lets you test to see the search results if a rule is removed from a query without actually deleting the rule. You can click the **Preview** toggle `on` to execute that rule in the query, or click **Preview** `off` to exclude it from the query. The query results display based on the rules included in the query. > [!NOTE] > > Your live site is *never* affected by setting the **Preview** toggle to `off`. ### Rule details When you click a specific rule, the Rule Details section displays. You can view rule information such as name, creation information, and the action such as boost or bury. In addition, you can scroll to see other information such as the history of changes to the rule, conflicts with other rules, and items linked to the rule. You can edit, delete, or duplicate the rule. If the rule status is `Draft`, you can click **Publish** to make the rule active on your site. If the rule status is `Published`, you can click **Unpublish** to deactivate the rule, or click **Edit** to open the rule for editing, then click **Save as Draft** to save your changes as a draft attached to the published rule — the live version continues to serve your site until you publish the draft. For more information, see [Manage rules](/docs/lw-platform/lw-cs/cstudio-rules#manage-rules). ![View rule details](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-editor-view-rule-details.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=fa41d0f2c5b4a43f16e24d1416b99831) ## Create new rules When you create a new rule in the Editor, the rule is triggered by the current query or category in the **Conditions Manager**. For example, when "party supplies" is the current query and you create and publish a rule, the rule is triggered only when end users search for "party supplies". Likewise, when "Rugs" is the current category, a new rule is triggered only when end users view the "Rugs" category on your site. There are several ways to create new rules in the Editor: * Click **Create Rule** in the Execute panel to open the Visual Builder and select a rule type. * Hold the pointer over any facet and click to create a facet rule. * Hold the pointer over any item card and click the controls to create a rule that applies that item. * Select the checkboxes for multiple items, then click the controls to create a rule that applies to that set of items. ![Item actions](https://mintcdn.com/lucidworks/TrcliI6cRUtIqv5P/assets/images/lw-platform/commerce-studio/lw-cs-item-actions.png?fit=max\&auto=format\&n=TrcliI6cRUtIqv5P\&q=85\&s=f79eae1ce5fb48d7983578d8fbfa4610) > [!TIP] > > You can also create rules directly on the [Rules](/docs/lw-platform/lw-cs/cstudio-rules) screen using the Form Builder, which provides a form-based interface without the live preview. ## View product details If you **Click for details**, the Product details panel displays and provides the following information: product name, image, position (ranking in results), triggered rules for the item, and the item analytics selected to view. **Product image, position, and price** ![Product image, position, and price](https://mintcdn.com/lucidworks/TrcliI6cRUtIqv5P/assets/images/lw-platform/commerce-studio/lw-cs-product-details1.png?fit=max\&auto=format\&n=TrcliI6cRUtIqv5P\&q=85\&s=ba5278d4002197a4d933af50f4543661) **Total revenue** ![Total revenue](https://mintcdn.com/lucidworks/TrcliI6cRUtIqv5P/assets/images/lw-platform/commerce-studio/lw-cs-product-details2.png?fit=max\&auto=format\&n=TrcliI6cRUtIqv5P\&q=85\&s=fb50a5b4b73f30b7836e64b0eede5102) **Total clicks and purchases** ![Total clicks and purchases](https://mintcdn.com/lucidworks/TrcliI6cRUtIqv5P/assets/images/lw-platform/commerce-studio/lw-cs-product-details3.png?fit=max\&auto=format\&n=TrcliI6cRUtIqv5P\&q=85\&s=9228407c1493676e657e258e0c78da54) ## Ranking insights This section displays the ranking factors for the results. Factors include: * **Sort**: Ranking signals such as relevance score * **Query processing**: Any rules that fired when creating the result set, such as phrase detections * **Analytics**: Selected performance metrics such as total revenue, total searches, total purchases, and average click position For more information about these and other metrics in Analytics Studio, see [types of metrics](/docs/lw-platform/lw-analytics/analytics-screen#types-of-metrics). **Sort factors** ![Sort factors](https://mintcdn.com/lucidworks/TrcliI6cRUtIqv5P/assets/images/lw-platform/commerce-studio/lw-cs-ranking-insights1.png?fit=max\&auto=format\&n=TrcliI6cRUtIqv5P\&q=85\&s=5fc2f5cd72af72e21b07b5447b9964e5) **Analytics** ![Analytics](https://mintcdn.com/lucidworks/TrcliI6cRUtIqv5P/assets/images/lw-platform/commerce-studio/lw-cs-ranking-insights2.png?fit=max\&auto=format\&n=TrcliI6cRUtIqv5P\&q=85\&s=3f84df3746fdd076e9ee1280b88b0e4c) **Total searches and purchases** ![Total searches and purchases](https://mintcdn.com/lucidworks/TrcliI6cRUtIqv5P/assets/images/lw-platform/commerce-studio/lw-cs-ranking-insights3.png?fit=max\&auto=format\&n=TrcliI6cRUtIqv5P\&q=85\&s=c2e12a2a40da99a773cd282e83167999) **Average click position** ![Average click position](https://mintcdn.com/lucidworks/yabQiFvt3JED8B7C/assets/images/lw-platform/commerce-studio/lw-cs-ranking-insights4.png?fit=max\&auto=format\&n=yabQiFvt3JED8B7C\&q=85\&s=dde6f67eca93be8662952a255d265b8a) ## Impressions metrics Product impressions measure the number of times a product displays in search results in response to user queries. The product is counted each time it displays, even if users do not interact further with the product. Impressions metrics can be displayed in [**Top Performing Products**](/docs/lw-platform/lw-analytics/analytics-screen#param-top-performing-products) in Analytics Studio and Commerce Studio Editor on the search results cards. For information about how to use impressions metrics to enhance product visibility and conversions, see [Impressions metrics usage](#impressions-metrics-usage). > **Analytics Studio Impressions metrics** > > If you select [**Top Performing Products**](/docs/lw-platform/lw-analytics/analytics-screen#param-top-performing-products) in Analytics Studio, the dashboard displays a column for the number of impressions per product. > > ![Top Performing Products dashboard with Impressions per product](https://mintcdn.com/lucidworks/vMCWPL7hzLnycFmk/assets/images/lw-platform/analytics/analytics-top-performing-products-impressions.png?fit=max\&auto=format\&n=vMCWPL7hzLnycFmk\&q=85\&s=43b8b4a4fa30c87a54ae42a9a791f0f0) > **Commerce Studio Impressions metrics** > > To enable impressions to display on product cards in Commerce Studio Editor, complete the following steps: > > 1. Navigate to Commerce Studio Settings and scroll to the [Inline Analytics section](/docs/lw-platform/lw-cs/cstudio-settings#inline-analytics). Click the toggle `on` for Inline Analytics. This setting is required to display the Metrics option in Commerce Studio Editor Preview Settings. If the toggle is `off`, you cannot display any metrics on search results cards in Commerce Studio Editor. > > ![Commerce Studio Settings enablement for Inline Analytics Metrics](https://mintcdn.com/lucidworks/vMCWPL7hzLnycFmk/assets/images/lw-platform/commerce-studio/lw-cs-settings-inline-analytics-toggle-dates.png?fit=max\&auto=format\&n=vMCWPL7hzLnycFmk\&q=85\&s=f7371856195238a40f27f77f0899f92b) > > Commerce Studio Setting enablement for Inline Analytics Metrics > > * **Metrics Duration.** The timeframe selected in the Metrics Duration field sets the default. But you can override this duration by selecting a different timeframe in Commerce Studio Editor Preview Settings Metrics. > > * **Document ID Field.** Enter the name of the search result document field used as the document ID when retrieving metrics from the Signals Store. The default is `id`. > > > [!NOTE] > > > > For detailed information, see [Commerce Studio inline analytics settings](/docs/lw-platform/lw-cs/cstudio-settings#inline-analytics). > > 2. Navigate to the Commerce Studio Editor screen and click **Preview Settings**. In the **Metrics** section, click the toggle to `on` for each metric you want to display on search results cards in Commerce Studio Editor. > > ![Commerce Studio Editor Preview Settings Metrics](https://mintcdn.com/lucidworks/vMCWPL7hzLnycFmk/assets/images/lw-platform/commerce-studio/lw-cs-editor-preview-settings-with-results.png?fit=max\&auto=format\&n=vMCWPL7hzLnycFmk\&q=85\&s=d65e7b7b6e1e764cbf50cd9a03a0ae55) > > Commerce Studio Editor Preview Settings Metrics > > The search results cards reflect all of the metrics selected. Here is an example with Impressions, Sales, and CVR metrics. > > ![Commerce Studio Editor product card with metrics](https://mintcdn.com/lucidworks/oD_48DY4nfwwUSpE/assets/images/lw-platform/commerce-studio/lw-cs-product-card-impression-metrics.png?fit=max\&auto=format\&n=oD_48DY4nfwwUSpE\&q=85\&s=c583de59aa067e972326c36be2fd9f9e) ### Impressions metrics usage Merchandisers can use impressions metrics information to help optimize and measure the effectiveness of customer search experiences. Ensuring the appropriate products display is essential to visibility and increased conversions. This section provides information about how merchandisers can use product impressions metrics to identify opportunities and take action in Commerce Studio. #### Understand the context for engagement metrics For example, a product with 1,000 impressions and 50 clicks has a 5% click-through rate, while a product with 50 impressions and 50 clicks has a 100% click-through rate. Without impression data, these scenarios appear identical. If a product has thousands of impressions but few clicks, consider taking the following actions to improve the potential for conversions. * Review product title, description, and image quality. * Check if the product is appearing for relevant search queries. * Consider adjusting product positioning or boosting rules. #### Identify product visibility gaps For example, products with high conversion rates but low impressions may be underexposed and represent missed revenue opportunities. If a product has a high click-through rate and conversion rate but limited impressions, consider taking the following actions to improve product visibility and enhance the potential for even more conversions. * Boost the product in relevant search queries to increase visibility. * Add merchandising rules to feature the product more prominently. * Ensure the product is properly categorized and tagged. #### Measure the impact of merchandising efforts For example, impressions metrics track how boosting rules, pinning, and other merchandising actions affect product visibility over time. If a previously visible product shows decreasing impression trends, consider taking the following actions to improve product visibility and enhance the potential for conversions. * Investigate if new products are displacing that product in search results. * Review relevancy rules and ensure the product matches user search intent. * Check inventory status and product availability. #### Expand the number of products with high impression-to-conversion ratios If most of the impressions are concentrated on a few products while others receive minimal exposure, consider taking the following actions to improve impressions for a greater number of products to enhance the potential for conversions. * Diversify search results to expose a broader product range. * Implement merchandising rules to rotate featured products. * Balance automated relevance with strategic product visibility. # Rewrites Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cstudio-query-rewrite You can configure query rewrite rules to help users find more relevant results. Create rules to account for underperforming or misspelled search terms, identify phrases to boost items, map synonyms to alternative search terms, and remove words from queries that limit the results returned. To learn more about the different rewrite rules, see [Types](#types). To start creating and publishing query rewrites, refer to the [Manage rewrites](#manage-rewrites) section. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Query rewrites vs. rules Query rewrites improve the accuracy and relevance of search results by modifying the query. In contrast, [rules](/docs/lw-platform/lw-cs/cstudio-rules) manipulate the ranking and presentation of search results. Query rewrites focus on the user’s intent. They take effect before the query is submitted and results are returned. ## Types There are several different types of rewrite rules to choose from depending on your use case. ### Underperforming Queries An underperforming rewrite, also known as a tail query rewrite, replaces a poorly-defined search term with an improved one. This function adds fields that are used as facets and tags to clarify intent, which improves the relevance of results. * B2B organizations use this feature to change vague or incomplete user entries and add structured information that clarifies user intent and enhances relevant results. For example, if a user enters a query using general terms, a query rewrite can add business-specific terminology to improve the results returned. * B2C organizations use this feature to interpret user entries that may be general or ambiguous and add fields that align with items in the product catalog. For example, you can create a tail query rewrite that replaces the query `iphone case yellow` with `iphone case yellow +color:"yellow"`, which uses the color field in your search facets. * Knowledge management organizations use this feature to tag incomplete or imprecise user queries with existing content to improve discoverability of site information. For example, if the user enters `set password`, the tags may include `set password +doc_type:"login credentials"`. ### Misspelling Detections A misspelling query rewrite detects and corrects common spelling mistakes. When a customer enters a search term containing a known misspelling, the incorrect spelling is replaced with the spelling correction. * B2B organizations enter corrections for industry-specific terminology, jargon, or technical terminology. For example, if your organization provides auto parts, a user might enter `brake petal`, so the correction would be `brake pedal`. * B2C organizations enter corrections to common misspellings of items in the product catalog. For example, if your customers frequently misspell or mistype the word `sweater` as `sweatre`, you can define an entry to correct it. * Knowledge management organizations enter terms from their content that users frequently misspell. For example, if medication clinical trials are part of the data, the user enters `metfrmin side effects`, so the correction your site enters would be `metformin`. ### Phrase Detections A phrase rewrite identifies phrases used in search terms so that products with matching phrases are boosted in the search results. This is helpful when users do not use quotation marks to identify phrases in their search terms. For B2B, B2C, and knowledge management organizations, this function adds quotation marks around the phrase the user enters to match the entire phrase and not the individual words of the phrase. For example, without phrase detection, a search for the words `remote control` would show results for both `remote` and `control`. With phrase detection, this search would correctly boost results for `"remote control"`. ### Synonym Detections You can specify synonyms for a query so that alternative words with the same meaning are automatically used in the search query. When a customer enters a search term with a synonym match, the alternative words are used instead of, or in addition to, the original search term. B2B, B2C and knowledge management organizations enter synonyms for products and content specific to their site. For example, a B2C organization might enter synonyms such as `pullover` and `jumper` for the search term `sweater`. Synonym query rewrites use one of two matching methods: * `ONEWAY` synonyms replace the original query with the synonym. Use a one-way synonym if you are confident the synonym is best for your product catalog. For example, a running specialty store may use a one-way synonym to rewrite the term `sneakers` to `running shoes`. * `SYMMETRIC` synonyms expand the query to include the original term and specified synonyms. Use a symmetric synonym when terms are used interchangeably (`sweater` and `pullover`) to increase the volume of results. ### Word Removal Use the remove words rewrite to simplify search queries and increase results. B2B, B2C, and knowledge management organizations determine words to remove that will improve query results for their site. For example, a B2C organization may rewrite the query `best wireless headphones` to remove the word `best`, which restricts the number of results returned. The improved query, `wireless headphones`, returns more results. > [!TIP] > > **FAQ: When should I use a remove words query rewrite instead of an underperforming rewrite?** > > Use a remove words query rewrite to broaden a query to include more results. Use an underperforming query rewrite to simplify a complex query (head) or expand a short query (tail). ## Manage rewrites To get started working with query rewrites, navigate to Commerce Studio and click **Rewrites** to display the Query Rewrites screen. ### Create a query rewrite 1. Click **Create Query Rewrite**. 2. In the **New Rewrite** panel, select the rewrite **Type** and complete its fields. ![Create Query Rewrite button and the Type list in the New Rewrite panel](https://mintcdn.com/lucidworks/eCJmeasVeA4I_nHO/assets/images/lw-platform/commerce-studio/lw-cs-query-rewrite-create.png?fit=max\&auto=format\&n=eCJmeasVeA4I_nHO\&q=85\&s=632ee073cff83919fdea9a5b0c496dba) The following tabs provide guidance for each type of rewrite: **Underperforming Queries** For **Type**, select **Enhance underperforming queries**. 1. In the **Tail Query** field, enter an underperforming query. For example, `latest shoes`. 2. In the **Improved Query** field, enter the replacement query. For example, `new shoes`. To add another query, click the plus icon. 3. Optional: In the **Description** field, describe the rewrite. For example, `improve to display new shoes`. **Misspelling Detections** For **Type**, select **Correct spelling errors**. 1. In the **Misspelled Query** field, enter a common misspelling. For example, `intertainment`. 2. In the **Suggested Correction** field, enter the correct spelling. For example, `entertainment`. To add another correction, click the plus icon. 3. Optional: In the **Description** field, describe the rewrite. For example, `correcting for entertainment`. **Phrase Detections** For **Type**, select **Detect Phrases**. 1. In the **Phrase** field, enter the phrase to detect. For example, `new shoes with low heels`. 2. Optional: In the **Description** field, describe the rewrite. For example, `phrase for new, low-heeled shoes`. **Synonym Detections** For **Type**, select **Add Synonyms**. 1. In the **Search Query** field, enter the term to add synonyms for. For example, `shoes`. 2. In the **Synonym** field, enter a synonym. For example, `sneakers`. To add another synonym, click the plus icon. 3. Select a **Synonym Matching Method**: * `ONEWAY` replaces the search query with the synonyms. * `SYMMETRIC` expands the search query to include the original term and the synonyms. 4. Optional: In the **Description** field, describe the rewrite. For example, `synonyms for shoes that are sneakers`. **Word Removal** For **Type**, select **Remove unnecessary words**. 1. In the **Words To Remove** field, enter the words to remove from queries. For example, `retro`. 2. In the **Trigger Phrases** field, enter a phrase that contains the words to remove. For example, `retro sneakers`. To add another phrase, click the plus icon. 3. Optional: In the **Description** field, describe the rewrite. For example, `remove retro to get all sneakers`. 3. Click **Publish** to make the rewrite active immediately, or click **Save as Draft** to save it unpublished. ### Edit a query rewrite Click a query rewrite to open its details panel, which shows its fields and history. You can edit, publish, and delete the rewrite from this panel. 1. In the details panel, click **Edit**. You can also select **Edit** from the row's actions menu. 2. Change the fields. You can't change the rewrite type. 3. Click **Save** to save your changes, or **Publish** to save and publish them. For a published rewrite, only **Publish** is available, so changes take effect immediately. ### Publish a query rewrite To publish a query rewrite, open its details panel, click **Publish**, and confirm. Published query rewrites take effect immediately. To unpublish a rewrite, click **Unpublish** instead. The **Rule State** column shows whether each rewrite is published. ### Delete a query rewrite To delete a query rewrite, do one of the following, and then confirm: * In the details panel, click **Delete**. * From the row's actions menu, select **Delete**. > [!WARNING] > > Query rewrites are deleted permanently. There is no way to undo this action. ### Bulk actions Select the checkboxes for multiple query rewrites to display bulk actions: * **Publish** publishes the selected unpublished rewrites. * **Unpublish** unpublishes the selected published rewrites. * **Export** downloads the selected rewrites as a CSV file. * **Delete** permanently deletes the selected rewrites. Each action shows how many rewrites it applies to. Publish, unpublish, and delete ask for confirmation. ## Effective workflows for teams Your team’s Data Analyst monitors Analytics Studio to identify low performing queries, recommends recommend which queries should be rewritten, and helps verify query rewrites are effective. Apart from the insights Analytics Studio provides, your team may start with existing industry knowledge. For example, some clothing brands prefer the term "pant" over "pants." Depending on your catalog, your team’s Product Manager may create a synonym query rewrite to treat the query `pants` the same as the query `pant`. Your Customer Experience Manager creates query rewrites based on knowledge of your customers' intent. For example, the CX Manager rewrites the query term `cheap` to the query terms `discount` or `sale`. These rewritten queries trigger rules that are used in a sales event. # Rules Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cstudio-rules Rules affect the order in which products appear in your search results. Rules let you pin, boost, bury, and block specific items in your catalog. You can also use rules to display custom banners, redirect customers to a different page on your site, set facets, and more. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio > **[Every rule in Commerce Studio](https://academy.lucidworks.com/paths/019cbff3-cf91-7ee8-a1e0-ea69743d60d1)** > > Learn how to use every rule type in Commerce Studio to improve search results and merchandising. This course provides detailed guidance on boost, pin, bury, block, facets, banners, redirects, and advanced configurations. Click your organization type to see examples of how to use rules to benefit your business goals: **Business-to-Consumer** B2C organizations use rules to promote items such as these to achieve business goals: * Products for marketing campaigns * New product launches * Products with inventory levels the organization wants to reduce * Any other business objective, such as increasing conversions For example, a boost rule could be applied to promote summer sandals and clothing for an end-of-summer promotion. **Business-to-Business** B2B organizations use rules to promote the most relevant items, services, and documents based on customer queries, and provide similar products and specifications based on customer intent. For example, if your organization sells computer memory components to distributors, the results include installation instructions and specifications that distributors can confirm and provide to their customers. **Knowledge Management** Knowledge management organizations use rules to retrieve and display the most relevant documents based on user queries. For example, an organization that provides scientific study results for medication clinical trials may pin the most recent results, while burying results for previous studies. ## Rules vs. query rewrites Both rules and query rewrites can be configured to help return the best search results to your users. Query rewrites allow you to alter and interpret search terms in multiple ways so relevant results are delivered. Rules changes the order in which search results are displayed, allowing you to promote certain items over others. Although query rewrites are configured in the [Rewrites](/docs/lw-platform/lw-cs/cstudio-query-rewrite) screen, you will see the effects of those rules on the Editor screen. ## How rules work Rules contain [conditions](#conditions) and [actions](#actions). When a condition or a combination of conditions is met, the rule performs an action. [Commerce Studio Rules](https://app.supademo.com/embed/cmucrswqh028qxr0jrcinhc43?embed_v=2\&utm_source=embed) ## Conditions You can trigger rules on a single condition or a combination of conditions. **Dates** `string` The date and time range for the rule. Click the field to select a date and time, or enter manually. For example, `05/15/2026 12:00`. **Field Value** `string` The field value to which the rule applies. For example, you can specify the `Color` field and set it to `Color: Black`. and multiple values for a given field to create more specific rules. For example, if you set the `Color` field to `Color: Black` and specify the `Brand` field to include multiple brands, then the rule triggers only if the Color and Brand field conditions are satisfied. **Query** `string` The query that triggers the rule. You must select a **Query Matching Method** to determine when a rule triggers. * **is**: The search query must match the defined term exactly. For example, if the rule is set to "\[is] black shoes", it only triggers when the user search is exactly "black shoes." * **contains**: The search query must include one or more of the defined terms anywhere within the query. Each word is evaluated independently. For example, if the rule is set to "\[contains] black shoes", it triggers for any query containing "black" (such as "black boots") and any query containing "shoes" (such as "running shoes"). The words do not need to appear together or in a specific order. * **contains phrase**: The search query must include the defined phrase in the exact word order entered. For example, if the rule is set to "\[contains phrase] black shoes", it triggers for "black shoes" or "men's black shoes," but not for "shoes black" or "black running shoes." * **starts with**: The search query must begin with the defined word or phrase. For example, if the rule is set to "\[starts with] winter", it triggers for "winter jackets" or "winter boots," but not for "jackets for winter." Multi-word phrases respect word order, so "\[starts with] winter jackets" triggers for "winter jackets sale" but not for "jackets winter sale." * **ends with**: The search query must end with the defined word or phrase. For example, if the rule is set to "\[ends with] manual", it triggers for "installation manual" or "product manual," but not for "manual installation guide." Multi-word phrases respect word order, so "\[ends with] near me" triggers for "pizza near me" but not for "near pizza me." **Query Profile** `string` Trigger this rule on a specified query profile. This value must match an existing Fusion query profile, which points to a specific configuration. > **Query matching methods** > > You must select a **Query Matching Method** to determine when a rule triggers: > > * **is**: The search query must match the defined term exactly. For example, if the rule is set to "\[is] black shoes", it only triggers when the user search is exactly "black shoes". > > * **contains**: The search query must include one or more of the defined terms anywhere within the query. Each word is evaluated independently. For example, if the rule is set to "\[contains] black shoes", it triggers for any query containing "black" (such as "black boots") and any query containing "shoes" (such as "running shoes"). The words do not need to appear together or in a specific order. > > * **contains phrase**: The search query must include the defined phrase in the exact word order entered. For example, if the rule is set to "\[contains phrase] black shoes", it triggers for "black shoes" or "mens black shoes," but not for "shoes black" or "black running shoes". > > * **starts with**: The search query must begin with the defined word or phrase. For example, if the rule is set to "\[starts with] winter", it triggers for "winter jackets" or "winter boots," but not for "jackets for winter". Multi-word phrases respect word order, so "\[starts with] winter jackets" triggers for "winter jackets sale" but not for "jackets winter sale". > > * **ends with**: The search query must end with the defined word or phrase. For example, if the rule is set to "\[ends with] manual", it triggers for "installation manual" or "product manual," but not for "manual installation guide". Multi-word phrases respect word order, so "\[ends with] near me" triggers for "pizza near me" but not for "near pizza me". > **[Commerce Studio: Starts With/ Ends With Rules](https://academy.lucidworks.com/training/019feca8-d6a0-744a-992e-3c23cbaf6cfa/overview)** > > Learn how to use the starts with and ends with query matching methods in Commerce Studio rules to trigger rules based on how a query begins or ends. ## Actions You can only apply one action per rule. Commerce Studio alerts you if you create multiple rules with conflicting actions. For example, a conflict occurs if you create rules that boost, block, and bury the same item. ### Rerank ![Boost action](https://mintcdn.com/lucidworks/84hgHnpjc8xFMsfB/assets/images/lw-platform/commerce-studio/actions/boost-pin-bury.png?fit=max\&auto=format\&n=84hgHnpjc8xFMsfB\&q=85\&s=76fc294cc59202f8704ae6661c6b6f0c) Boost, pin, bury #### Boost Increases the ranking of one or more products so they move up in the search results. ##### Boost by attributes Boosts items in the search results that match selected attributes, based on the weight given the attribute in a slider. This is the recommended type of boost because it adapts to changing catalogs and reflects a broader merchandising strategy. This demo describes how to create a boost rule by specifying attributes in the Commerce Studio Rules screen (Form Builder). [Boost by Attribute](https://app.supademo.com/embed/cmuczuywh07fpqmgl2gnumtey?embed_v=2\&utm_source=embed) > [!NOTE] > > If you click **Create Rule** and then select **Visual Builder**, the Commerce Studio Editor screen displays and you can create a rule from that screen. You can boost items based on multiple attributes, including multiple values in one category. * **Within a single attribute**: When you select multiple values for one attribute (for example, `Color: Black, Gray`), items matching any of those values are included using **OR logic**, so items matching either Black or Gray are boosted. * **Across multiple attributes**: You can combine different attribute categories using **AND logic** for more granular targeting. For example, if you set `Color: Black, Gray` AND `Count: 40, 50`, the rule boosts only black or gray items that come in packs of 40 or 50. Items must match at least one value from each attribute category. > [!NOTE] > > Existing attribute rules continue to use OR logic between attributes, ensuring backward compatibility for older rules. > **Boost Param examples** > > The **Boost Param** dropdown sets how the boost is applied to matching products. > Enter your query expression in the **Boost Query** field. > > | Boost Param | Boost Query example | Effect on products | > | - | - | - | > | `bq` | `category_s:"Small Business"^5` | Additive. Products matching the query receive an extra relevance boost on top of their normal ranking. The number after `^` sets how much weight to add. | > | `boost` | `if(termfreq(brand_s,'Acme'),10,1)` | Multiplicative. Products where the condition is true have their score multiplied by the specified number (here, 10×). Products where the condition is false are multiplied by 1 (unchanged). | This rule type also supports these comparison operators for numerical fields: * **Equals** matches the specified value exactly (text or numeric). * **Greater than** matches numeric values greater than the specified number. * **Less than** matches numeric values less than the specified number. * **Greater than or equal to** matches numeric values greater than or equal to the specified number. * **Less than or equal to** matches numeric values less than or equal to the specified number. * **Between** matches numeric values within the specified range (inclusive). * **Not equal to** excludes values that match the specified value exactly. > [!NOTE] > > Numeric comparison operators and boosting by AND attributes require Fusion 5.17.1 or later. ##### Boost items Boosts specific items to the top of the results. These items must be identified individually. This approach is more precise but less flexible than boost by attributes. #### Pin items Pins products to an exact location within search results. This allows precise control over product placement. For example, you can ensure certain products always appear next to each other. > [!NOTE] > > Another example is that you can pin a product to a specific position that reliably appears on page 2 after pagination. This capability requires the applicable Fusion patch to be installed. For more information, contact your Lucidworks support representative. #### Bury Moves selected items to the bottom of search results. Unlike the Block action, products are not removed entirely from the search results. ##### Bury by attributes Buries items in the search results that match selected attributes, based on the weight given the attribute in a slider. This is the recommended type of bury for the same reasons as boost by attributes. For example, you can use this to de-emphasize a particular brand in your results without removing it entirely. > [!NOTE] > > The steps to bury by attributes are the same as those described in the [Boost by attributes](#boost-by-attributes) demo, except you would select the **Bury** in the **Action** field. You can bury items based on multiple attributes, including multiple values in one category. * **Within a single attribute**: When you select multiple values for one attribute (for example, `Color: Black, Gray`), items matching any of those values are included using **OR logic**, so items matching either Black or Gray are buried. * **Across multiple attributes**: You can combine different attribute categories using **AND logic** for more granular targeting. For example, if you set `Color: Black, Gray` AND `Count: 40, 50`, the rule buries only black or gray items that come in packs of 40 or 50. Items must match at least one value from each attribute category. > [!NOTE] > > Existing attribute rules continue to use OR logic between attributes, ensuring backward compatibility for older rules. This rule type also supports these comparison operators for numerical fields: * **Equals** matches the specified value exactly (text or numeric). * **Greater than** matches numeric values greater than the specified number. * **Less than** matches numeric values less than the specified number. * **Greater than or equal to** matches numeric values greater than or equal to the specified number. * **Less than or equal to** matches numeric values less than or equal to the specified number. * **Between** matches numeric values within the specified range (inclusive). * **Not equal to** excludes values that match the specified value exactly. > [!NOTE] > > Numeric comparison operators and burying by AND attributes require Fusion 5.17.1 or later. ##### Bury items Buries specific items to the bottom of the results. These items must be identified individually. Like boost items, this approach is more precise but less flexible than bury by attributes. #### Block Removes selected items from search results entirely. Blocked items don't appear for matching searches. ##### Block by attributes Applies block based on selected attributes. Products matching the specified attributes are completely removed from search results. You can block items based on multiple attributes, including multiple values in one category. * **Within a single attribute**: When you select multiple values for one attribute (for example, `Color: Black, Gray`), items matching any of those values are included using **OR logic**, so items matching either Black or Gray are blocked. * **Across multiple attributes**: You can combine different attribute categories using **AND logic** for more granular targeting. For example, if you set `Color: Black, Gray` AND `Count: 40, 50`, the rule blocks only black or gray items that come in packs of 40 or 50. Items must match at least one value from each attribute category. > [!NOTE] > > Existing attribute rules continue to use OR logic between attributes, ensuring backward compatibility for older rules. This rule type also supports these comparison operators for numerical fields: * **Equals** matches the specified value exactly (text or numeric). * **Greater than** matches numeric values greater than the specified number. * **Less than** matches numeric values less than the specified number. * **Greater than or equal to** matches numeric values greater than or equal to the specified number. * **Less than or equal to** matches numeric values less than or equal to the specified number. * **Between** matches numeric values within the specified range (inclusive). * **Not equal to** excludes values that match the specified value exactly. > [!NOTE] > > Numeric comparison operators and blocking by AND attributes require Fusion 5.17.1 or later. ##### Block items Applies block to specific products that must be identified individually. These products will be completely removed from search results. ### Facets #### Manage facets Customizes which facet categories appear in the query response, their display order, and their individual configuration settings. For example, if your site sells clothing, you can configure facet categories for brand, color, price, size, and other attributes. Each facet category can be extensively customized to control how values are displayed and how users interact with them. > **Advanced configuration options** > > **Type** `enum` *required* (default: Term) > > Specifies how facet values are generated. **Term** generates discrete values like brand names or colors. **Gap Range** generates numeric ranges like price brackets or size ranges. > > **Value Selection** `enum` *required* (default: Multi-select) > > Controls how users can select facet values. **Single-select** allows users to choose only one value at a time. **Multi-select** allows users to choose multiple values simultaneously. > > **Value Order** `enum` *required* (default: Count) > > Determines how facet values are sorted. **Index** sorts values in alphabetical or numeric order. **Count** sorts values by the number of matching products. > > **Minimum Count** `integer` *required* (default: 1) > > Sets the minimum number of matching products required for a facet value to be displayed. Values with fewer matches will be hidden from the facet list. > > **Boost Values** `array` > > Promotes specific facet values higher in the list, making them appear more prominently to users. > > **Bury Values** `array` > > Moves specific facet values lower in the list, de-emphasizing them without removing them entirely. > > **Block Values** `array` > > Removes specific facet values from display entirely, preventing them from appearing in the facet list. ### Advanced #### Add banner Associates an image URL with a search rule and includes it in the search results JSON response. You can specify the image URL and optionally define a page zone identifier. Your frontend application can then consume this data to dynamically display promotional banners or images alongside the corresponding search results. **Banner URL** `string` *required* The URL of the image to display as a banner. **Banner Zone** `string` An identifier specifying which zone or area of the page the banner should appear in. > **Response JSON example** > > ```json theme={"dark"} > "banner": [{ > "url": "https://example.com/assets/holiday-banner.png", > "zone": "top-wide" > }] > ``` #### Filter items Applies [filter queries](https://solr.apache.org/guide/common-query-parameters.html) (`fq`) to the query and changes the results so a pre-selected set of content displays. #### Set JSON configuration Allows you to define a custom JSON blob that will be included in the search results response. You can input any valid JSON structure, which your frontend application can then interpret and use for custom functionality. This provides flexibility to pass arbitrary data alongside search results for frontend consumption. **Blob type** `string` An optional identifier used primarily for categorizing or identifying the blob. **JSON blob** `string` *required* The custom JSON blob to include in the search results response. > **Response JSON example** > > ```json theme={"dark"} > "jsonBlob": { > "example-blob": [{ > "event": "Black Friday Sale 2026", > "startDate": "11/27/2026 00:00", > "endDate": "11/27/2026 23:59", > "description": "Our biggest sale of the year! Save up to 70% on select items during our Black Friday event.", > "banner": { > "url": "https://example.com/assets/black-friday-2026-banner.png", > "zone": "top-wide" > }, > "promotionCode": "BF2026" > }] > }, > ``` #### Redirect Includes a redirect URL in the search results JSON response. Your frontend application can consume this data to redirect users to a specific destination, such as dedicated landing pages or custom pages for queries that return zero results. **Path or URL** `string` *required* The URL or path to redirect users to. > **Response JSON example** > > ```json theme={"dark"} > "redirect": ["https://example.com/new-location"] > ``` #### Set response value Sends an arbitrary value to the frontend or pipeline to trigger another action. This action can be combined with other actions within the same rule. For example, an e-commerce website may use the response value action to display an advertisement. #### Set parameters Sets a [parameter name and value](https://solr.apache.org/guide/solr/latest/query-guide/common-query-parameters.html) to a search query. For example, the sort order for the results, or a filter that affects results. ## Advanced Grouping Advanced grouping is a conditional, rule-based approach to product [variant grouping](/docs/lw-platform/lw-cs/cstudio-settings#variants) that enables different grouping behaviors based on rules. You can implement advanced grouping using the Set Parameters rule type. When you create a Set Parameters rule that includes the required grouping parameters, Commerce Studio automatically detects and enables grouping for queries where the rule conditions are met. This conditional behavior means grouping can activate for some searches but not others, based on your rule configuration. Advanced grouping enables scenarios like these: * Apply color-based grouping for apparel queries but ID-based grouping for electronics * Group by size for furniture searches but by style for home decor * Enable grouping only for specific categories or query types * Switch grouping fields based on seasonal campaigns or promotions ### Enable advanced grouping To enable advanced grouping, your Set Parameters rule must include the following: **expand.rows** `number` *required* Controls how many variants to display per group. **expand** `boolean` *required* Must be set to `true` to enable expansion. **fq** `string` *required* Contains the Solr `collapse` syntax that defines the grouping field. Here's an example of the syntax for the `fq` parameter: ``` {!collapse tag=collapse field=FIELD_NAME nullPolicy=expand} ``` It includes the following parameters: **tag** `string` *required* This must be set to `collapse`. **field** `string` *required* The field to group by (for example, `id`, `color_s`, `product_family_s`). **nullPolicy** `string` *required* Determines behavior for items without a value in the grouping field (typically `expand`). ### Example configurations These example configurations illustrate how to configure advanced grouping for different scenarios: **Group by product ID** ``` {!collapse tag=collapse field=id nullPolicy=expand} ``` **Group by color** ``` {!collapse tag=collapse field=color_s nullPolicy=expand} ``` **Group by custom field** ``` {!collapse tag=collapse field=Collapse_Field_s nullPolicy=expand} ``` ## Rule edit states Facet rules in Commerce Studio support draft and published states, allowing you to prepare changes before making them live. ### Draft and published states When you create or modify a facet rule, you can save it as a draft without immediately publishing it to your live site. Drafts support the following tasks: * Prepare changes in advance * Review configurations before going live * Test rule behavior internally A draft rule is not active on your site until you explicitly publish it. Once published, the rule becomes active and affects search results. ### Concurrent editing Commerce Studio does not lock rules when multiple users edit them. If two users edit the same facet rule simultaneously, the last user to save their changes will overwrite any previous modifications. Commerce Studio does not maintain version history for rules, so there is no way to recover overwritten changes. To avoid conflicts, coordinate with team members before editing the same rule. ## Create rules Commerce Studio offers two ways to create rules: the Visual Builder and the Form Builder. ### Visual Builder The Visual Builder lets you create rules while previewing live search results in the [Editor](/docs/lw-platform/lw-cs/cstudio-editor). Use this approach when you want to see how a rule affects item ranking in context as you configure it. [Create a rule in Commerce Studio Editor](https://app.supademo.com/embed/cmjd7f1gn01s64e35foztaypg?embed_v=2\&utm_source=embed) > [!NOTE] > > More information about creating rules in the Editor, including options to create rules for individual items, is in the [Commerce Studio Editor](/docs/lw-platform/lw-cs/cstudio-editor) topic. ### Form Builder The Form Builder lets you create rules directly on the Rules screen without the live preview. Use this approach when you know exactly what rule you want to create and do not need to see the search results in context. ![Form Builder](https://mintcdn.com/lucidworks/v8Oy1RZSpfLxwDN_/assets/images/lw-platform/commerce-studio/manual-builder.png?fit=max\&auto=format\&n=v8Oy1RZSpfLxwDN_\&q=85\&s=189b3f0ac3af40770dfd20f5b075fdd9) Form Builder in Commerce Studio To create a rule using the Form Builder: **1. Open the Form Builder** On the Rules screen, click **Create Rule** and select **Form Builder**. **2. Configure the rule fields** Configure the rule fields in the panel that appears. > **Configuration options** > > **Name** `string` *required* > > A name for the rule. You can edit this at any time. > > **Precedence** `integer` *required* > > Determines when rules should take effect in relation to other triggered rules. A higher number means higher precedence. For example, a rule with precedence of `10` will take effect before a rule with precedence of `3`. If two rules have the same precedence, the newer rule takes effect first. > > **Conditions** `object` *required* > > The conditions that trigger the rule. These correspond to the condition types described in [Conditions](#conditions). > > **Action** `enum` *required* > > The action the rule performs when its conditions are met. Select an action type from the dropdown. The form updates to show the configuration fields for that action type. For details on each action type, see [Actions](#actions). > > **Description** `string` > > Optional text describing the purpose of the rule. **3. Save or publish the rule** Click **Save as Draft** to save the rule without publishing it, or click **Publish** to make it immediately active on your site. To edit a rule that is already published, see [Edit a published rule](#edit-a-published-rule). ## Manage rules The Rules screen lists all rules in your Commerce Studio environment and is where you publish, edit, filter, and perform bulk actions on them. ### Rule states Each rule on the Rules screen is in one of the following states: * **Published.** The rule is active on your site. * **Draft.** The rule is saved but is not active on your site. * **Published with draft edits.** A published rule has unpublished edits saved as a draft. The published version remains active on your site, and the draft appears as a second row beneath it so you can see and act on both. ### Edit a published rule When you edit a published rule, the published version continues to serve your site until you explicitly publish the changes. Your edits are shown in the Editor as a draft so you can preview their impact without affecting customers. When you finish editing, click **Publish** to replace the published version with your edits and apply them to your site immediately. Alternatively, click **Save as Draft** to save your edits as a draft attached to the published rule. The published version remains live, and the draft appears beneath it on the Rules screen. > [!NOTE] > > A published rule can have only one draft edit at a time. If a draft already exists, opening the rule for editing adds to the existing draft. ### Manage a published rule with draft edits When a published rule has draft edits, both versions appear as two rows on the Rules screen. The actions available depend on which row you act on. On the **published row**: * **Edit** is disabled. Edits must be made to the draft version. * **Delete** removes both the published rule and the draft edits. * **Duplicate** is disabled. The draft edits must be published or deleted before the rule can be duplicated. * **Unpublish** unpublishes the rule and deletes the draft edits. On the **draft row**: * **Edit** opens the draft for further editing. * **Delete** discards the draft and restores the rule to the published version. * **Publish** replaces the published version with the draft and applies it to your site. ### Bulk actions When you select multiple rules from the Rules screen, the bulk action options let you update all of the selected rules at one time. Watch this demo to learn how to select multiple Commerce Studio rules and update them all at once. [Bulk Update Commerce Studio Rules](https://app.supademo.com/embed/cmulegwjl039aqm9gfcgrwrrc?embed_v=2\&utm_source=embed) The following bulk options are available based on the rules selected. > **Publish multiple rules** > > 1. After you select the rules to publish, click **Publish** from the bulk action option bar. The confirmation window displays, and indicates any rules that conflict with the rules you want to publish. > > ![Publish multiple rules](https://mintcdn.com/lucidworks/MZm7JbZrphVMs8Fh/assets/images/lw-platform/commerce-studio/actions/cs-rules-bulk-publish.png?fit=max\&auto=format\&n=MZm7JbZrphVMs8Fh\&q=85\&s=d7cf314fc7cbfffaa5384d0d2d72e48c) > > Publish multiple rules > > 2. To proceed, click **Publish**. > **Unpublish multiple rules** > > 1. After you select the rules to unpublish, click **Unpublish** from the bulk action option bar. The confirmation window displays and indicates the number of rules to unpublish. > > ![Publish multiple rules](https://mintcdn.com/lucidworks/MZm7JbZrphVMs8Fh/assets/images/lw-platform/commerce-studio/actions/cs-rules-bulk-unpublish.png?fit=max\&auto=format\&n=MZm7JbZrphVMs8Fh\&q=85\&s=ab4645087b863a907c5d3a3e2e8efd15) > > Unpublish multiple rules > > 2. To proceed, click **Unpublish**. > **Edit multiple rules** > > 1. After you select the rules to modify, click **Edit** from the bulk action option bar. > > ![Publish multiple rules](https://mintcdn.com/lucidworks/MZm7JbZrphVMs8Fh/assets/images/lw-platform/commerce-studio/actions/cs-rules-bulk-edit.png?fit=max\&auto=format\&n=MZm7JbZrphVMs8Fh\&q=85\&s=befc6812c5f9a1c5cd3c8e20382d8aaf) > > Edit multiple rules > > 2. Click the **Tags** field to select from the list. If you click **+** you can add another tag. > > 3. Click the **Query Profiles** field to select from the list. If you click **+**, you can add another query profile. > > 4. Select either **Save as Draft** or **Publish changes** for the rules you are editing. > > > [!NOTE] > > > > If you select to change a rule that has existing draft edits, this edit overwrites those existing edits. > > 5. Click **Apply** to save the changes to the selected rules. > **Migrate multiple rules to a different Commerce Studio environment** > > This option lets you select multiple rules to migrate from one Commerce Studio environment to a different Commerce Studio environment. For example, you might want to migrate rules in your Development environment to your Production environment. > > > [!WARNING] > > > > Before you use this option, the following issues need to be considered. > > > > * The bulk migration doesn't let you filter which rules are migrated by author, label, campaign, or tag. > > > > * The bulk migration doesn't detect if a rule already exists in the target environment that might conflict with a rule being migrated. > > > > * It is vital to preview what will change before committing to the migration. > > 1. After you select the rules you want to migrate from one Commerce Studio environment to a different Commerce Studio environment, click **Migrate** from the bulk action option bar. > > ![Migrate multiple rules to a different Commerce Studio environment](https://mintcdn.com/lucidworks/MZm7JbZrphVMs8Fh/assets/images/lw-platform/commerce-studio/actions/cs-rules-bulk-migrate.png?fit=max\&auto=format\&n=MZm7JbZrphVMs8Fh\&q=85\&s=0bc4e5ccdd8991811e21634de7ae9ad5) > > Migrate multiple rules to a different Commerce Studio environment > > 2. Click the **Target Environment** field to select from the list. > > 3. Select either to migrate the selected rules and designate the rules with the **Draft** or **Published** status. > > 4. Click **Migrate** to complete the migration of those rules. > > 5. Access the target Commerce Studio environment and verify the rules migrated correctly. > **Export multiple rules to a CSV file** > > This option lets you select rules and export them to a CSV file for processing outside of Commerce Studio. > > After you select the rules to export, click **Export** from the bulk action option bar. The rules are written to a CSV file that is saved to your computer. > **Delete multiple rules** > > After you select rules you want to remove, click **Delete** from the bulk action option bar. Click **Delete** to confirm the removal of the rules and any draft edits on those rules. > > > [!WARNING] > > > > The selected rules and **any draft edits** on the rules are deleted using this process. Verify that is the action you want to take before confirming the deletion. > **Deselect the rules currently selected** > > To deselect all of the rules currently selected on the screen, click **Deselect** from the bulk action bar. ## Examples to improve search results using rules Commerce Studio allows you to apply targeted actions when a search query contains specific terms. These actions don't require code changes and support the following business goals: * Improved relevance * Faster discovery of the content users are seeking This section provides examples of how to use rules to improve search results. **Ecommerce** B2B and B2C organizations can use rules to improve product discovery and merchandising outcomes by performing the following actions. These examples describe some actions for a bookstore website. * **Promote high-priority products.** Boost books from a popular series so they appear higher in search results when users search by author name. * **Remove outdated or unavailable items.** Block discontinued titles to ensure only relevant, purchasable books appear in results. * **Highlight specific products.** Boost selected new or overstocked titles to increase visibility and drive sales. * **Refine results by intent.** Filter results to show only children’s and young adult books when users search for children’s content. * **Improve ranking within related groups.** Boost items within a series so the most popular titles appear first when users search for that series. * **Target branded searches.** Use "\[starts with]" to boost promotional campaigns when users begin their query with a specific brand name, without affecting queries where the brand appears later in the query. * **Support location-based queries.** Use "\[ends with] near me" to apply location-specific filtering or boosting logic for geo-modified searches. * **Manage available facets.** Display genre facets on the homepage and top author facets on search results pages to help users refine results. * **Apply advanced configurations.** Use a `Set Banner` rule to display a promotional banner when users search for mystery titles. **Knowledge management** B2B, B2C, and Knowledge management organizations can use rules to improve user search experiences for documents on their site by performing the following actions. For example, organizations could set rules to enhance the discovery of internal policies and procedures for employees, and different rules for searches about external, customer-facing policies, procedures, and product specifications. These examples describe some actions that can be applied to knowledge and support content to reduce friction and guide users quickly. * **Surface critical content.** Pin a gift card information document to the top of results for searches including the term, "gift". * **Guide users to key destinations.** Redirect users to a "Contact Us" page when they search for terms such as "email" or "contact". * **Target support documentation.** Use "\[ends with] manual" to boost user manuals and product documentation, or use "\[ends with] pdf" to prioritize downloadable resources. * **De-emphasize outdated content.** Bury notices related to discontinued programs so they appear lower in results. * **Prioritize important documents.** Redirect to the privacy policy page when a user searches for "privacy policy". * **Manage grouped content visibility.** Bury older product support documents within a group while pinning new program information to the top for related searches. # Settings Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cstudio-settings In Commerce Studio's settings, you can configure what the [Editor](/docs/lw-platform/lw-cs/cstudio-editor) displays for each search profile. Some of these settings require the names of data fields in Fusion, but you can type to search for the fields you need. In your site on Lucidworks Platform, navigate to **Commerce Studio** > **Settings** to access these settings. Start by selecting a search profile to configure. Search profiles represent different predefined search results that you can display on different pages of your customer-facing site, such as new items, seasonal items, sale items, and so on. You might also have experimental search profiles for testing different configurations. The configuration you create here determines how the item cards are displayed in the Editor when the same search profile is selected. ![Select a search profile](https://mintcdn.com/lucidworks/NXdmPj01VTcfSoKs/assets/images/lw-platform/commerce-studio/lw-cs-settings-profile-select.png?fit=max\&auto=format\&n=NXdmPj01VTcfSoKs\&q=85\&s=4fb8acc4e6703e1e9b0d5e61e609d2fe) ## Configure Search Results In the **Search Results** section, you can configure the fields displayed for each result item in the Editor. Once you configure these settings, you can turn different display fields on or off while you're working in the Editor using its [Preview Settings](/docs/lw-platform/lw-cs/cstudio-editor#configure-the-item-card-display). ![Configure search results Preview](https://mintcdn.com/lucidworks/NXdmPj01VTcfSoKs/assets/images/lw-platform/commerce-studio/lw-cs-settings-search-results.png?fit=max\&auto=format\&n=NXdmPj01VTcfSoKs\&q=85\&s=a2b50842fcdf2894d0c8f451b384feea) ![Configure search results Inline Analytics](https://mintcdn.com/lucidworks/NXdmPj01VTcfSoKs/assets/images/lw-platform/commerce-studio/lw-cs-settings-search-results1.png?fit=max\&auto=format\&n=NXdmPj01VTcfSoKs\&q=85\&s=676beed6f98b47018ea89346866c2e66) ![Configure search results Category and Typeahead](https://mintcdn.com/lucidworks/NXdmPj01VTcfSoKs/assets/images/lw-platform/commerce-studio/lw-cs-settings-search-results2.png?fit=max\&auto=format\&n=NXdmPj01VTcfSoKs\&q=85\&s=c4e46670e1fa6f679e5ef1ee51cb5777) ### Layout The **Layout** section lets you select to display search results in a vertical list or a grid pattern. ![List layout setting](https://mintcdn.com/lucidworks/NXdmPj01VTcfSoKs/assets/images/lw-platform/commerce-studio/lw-cs-settings-layout.png?fit=max\&auto=format\&n=NXdmPj01VTcfSoKs\&q=85\&s=f9fc0259999200dcb39060eaae429645) Select the option you want, click **Save**, and then verify the list displays on the Editor screen. This demo explains the Layout options and how each displays search results. [Search Results Layout in Commerce Studio](https://app.supademo.com/embed/cmt921799057eqmz1o5r8xw81?embed_v=2\&utm_source=embed) ### Fields Style Under **Fields Style**, you can select and format the fields that the preview cards display in the Editor. * To add a field, click the button. * To change a field, click the field and type to search for another one. * To change a field's display style, click the dropdown and select the style that best matches the field's data type. ### Variants When you enable Variants, you can select the fields that contain data about different variants of your products. To enable product grouping in Commerce Studio, follow the procedure for your configuration. **Fusion** If you are using Fusion, configure grouping in your query pipeline. Then, configure grouping in Commerce Studio. **1. Open your query pipeline** In Fusion, open the query pipeline for which you want to configure grouping. **2. Add query parameters** The query profile must pass a `fq`, `expand`, and `expand.rows` query parameters. 1. Add a new **Additional Query Parameters** pipeline stage or edit an existing one. 2. Add the following query parameters: **fq** `string` **Parameters and Values** **Parameter Name** `string` *required* `fq` **Parameter Value** `string` *required* `{!collapse field=FIELD_NAME}` **Update Policy** `enum` *required* `default` **expand** `boolean` **Parameters and Values** **Parameter Name** `string` *required* `expand` **Parameter Value** `boolean` *required* `true` **Update Policy** `enum` *required* `default` **expand.rows** `number` **Parameters and Values** **Parameter Name** `string` *required* `expand.rows` **Parameter Value** `number` *required* The number of variant swatches displayed on each product card in Commerce Studio. For example, `5` displays 5 variant swatches on the product card. All variants are included in the response regardless of this value. This parameter must be set in Fusion or in the same Set Parameter Rule as the collapse parameter. **Update Policy** `enum` *required* `default` 3. Save the pipeline stage and pipeline configuration. 4. Verify that your query pipeline passes the query parameters you set up in previous steps. In the query workbench, open the **View As** selector and select JSON. Navigate to `responseHeader.params` in the response. ![Query parameters in the response JSON](https://mintcdn.com/lucidworks/8GeHMfZ_Pzc-4YpW/assets/images/lw-platform/commerce-studio/lw-cs-settings-variants-fusion-json.png?fit=max\&auto=format\&n=8GeHMfZ_Pzc-4YpW\&q=85\&s=cde903377330784da635b70380ccde49) Query parameters in the response JSON > [!NOTE] > > Setting a parameter requires proper Solr syntax. If you receive errors in Commerce Studio after completing these steps, verify that you set up these parameters correctly. **3. Configure Commerce Studio** Go to **Commerce Studio** > **Settings** and configure these options: ![Variant settings in Commerce Studio](https://mintcdn.com/lucidworks/8GeHMfZ_Pzc-4YpW/assets/images/lw-platform/commerce-studio/lw-cs-settings-variants.png?fit=max\&auto=format\&n=8GeHMfZ_Pzc-4YpW\&q=85\&s=c0f516ddb79162e2535b1d4673ca3e16) Variant settings in Commerce Studio **Variant Field Name** `string` The Fusion field containing visual data (image path or color) used for variant swatches on the product card. This information is used for visual display purposes only. **Variant Field Type** `enum` Specifies whether the variant field name contains an `image` or `color`, determining which type of swatch Commerce Studio displays. This information is used for visual display purposes only. **Variant SKU ID** `string` The field containing IDs of individual products collapsed into a single group in the Editor. This information is used for visual display of variant swatches and for creating rules to rerank products within the group. > [!NOTE] > > These configurations determine how products with variants are visualized in the Editor. **4. Verify your settings** Save your changes, then visit the Editor to verify that items are correctly grouped. **Core Settings** If you are using Core Settings, enable product grouping in the Lucidworks Platform UI. **1. Turn it on** Go to **Core Settings** > **Relevance** and turn on **Product Grouping**: ![Product Grouping toggle in Core Settings](https://mintcdn.com/lucidworks/8GeHMfZ_Pzc-4YpW/assets/images/lw-platform/core-settings/product-grouping.png?fit=max\&auto=format\&n=8GeHMfZ_Pzc-4YpW\&q=85\&s=66ab01620ba986afafa89d50ce608573) Product Grouping toggle in Core Settings **2. Configure Commerce Studio** Go to **Commerce Studio** > **Settings** and configure these options: ![Variant settings in Commerce Studio](https://mintcdn.com/lucidworks/8GeHMfZ_Pzc-4YpW/assets/images/lw-platform/commerce-studio/lw-cs-settings-variants.png?fit=max\&auto=format\&n=8GeHMfZ_Pzc-4YpW\&q=85\&s=c0f516ddb79162e2535b1d4673ca3e16) Variant settings in Commerce Studio **Variant Field Name** `string` The Fusion field containing visual data (image or color) used for variant swatches on the product card. For visual display purposes only. **Variant Field Type** `enum` Specifies whether the variant field name contains an `image` or `color`, determining which type of swatch Commerce Studio displays. For visual display purposes only. **Variant SKU ID** `string` The field containing IDs of individual products collapsed into a single group in the Editor. This information is used for visual display of variant swatches and for creating rules to rerank products within the group. **3. Verify your settings** Save your changes, then visit the Editor to verify that items are correctly grouped. > [!TIP] > > For conditional, rule-based grouping that can vary based on queries, categories, or other conditions, see [advanced grouping](/docs/lw-platform/lw-cs/cstudio-rules#advanced-grouping) in the Rules documentation. ### Inline Analytics When you configure and use the signals beacon and Analytics Studio to collect and display signal information, you can also enable Inline Analytics in Commerce Studio Settings, which lets you select the metrics to display in Commerce Studio Editor search results cards. > **Enable Commerce Studio Impressions metrics** > > To enable metrics to display in Commerce Studio, complete the following steps: > > 1. Navigate to Inline Analytics and click the toggle `on`. > > > [!NOTE] > > > > IMPORTANT: This setting is required to display the Metrics option in Commerce Studio Editor Preview Settings. If the toggle is `off`, you cannot display any metrics on search results cards in Commerce Studio Editor. > > ![Commerce Studio Settings enablement for Inline Analytics Metrics](https://mintcdn.com/lucidworks/vMCWPL7hzLnycFmk/assets/images/lw-platform/commerce-studio/lw-cs-settings-inline-analytics-toggle-dates.png?fit=max\&auto=format\&n=vMCWPL7hzLnycFmk\&q=85\&s=f7371856195238a40f27f77f0899f92b) > > Commerce Studio Setting enablement for Inline Analytics Metrics > > 2. Select a default option in the **Metrics Duration** field. This is the default duration for the Commerce Studio Editor Preview Settings Metrics section. Options include Last Hour, Last 24 Hours, Last 7 Days, Last 30 Days, and Last Year. > > > [!NOTE] > > > > The timeframe selected in the Metrics Duration field is the default. But you can override this duration by selecting a different timeframe in Commerce Studio Editor Preview Settings Metrics. > > 3. In the **Document ID Field**, enter the name of the search result document field used as the document ID when retrieving metrics from the Signals Store. The default is `id`. > > > [!NOTE] > > > > This is the Solr field that corresponds to the product identifier that your signals beacon logs for each item. The default value of `id` matches the Solr `uniqueKey` for most catalogs. However, use the value your catalog uses. Another example of the value used is `sku_s`. > > This value is used to calculate the search result's Impressions, ATC, > Orders, Sales, RPV, and CVR data on the result card. > > > [!WARNING] > > > > If the Document ID Field doesn't match what your signals beacon records as the product identifier, the metrics cannot be calculated and a `--` placeholder displays on the result card. > > 4. Optionally, if you want to build a preview of how metrics display on the search result card before you deploy it in Commerce Studio Editor, you can select the metrics checkboxes for Impressions, Add-To-Cart (ATC), Orders, Sales, Revenue Per Visit (RPV), and Conversion Rate (CVR). > > In this example, all of the checkboxes except Impressions are checked, and the Settings Preview Result Card indicates how that displays: > > ![Configure search results Preview](https://mintcdn.com/lucidworks/vMCWPL7hzLnycFmk/assets/images/lw-platform/commerce-studio/lw-cs-settings-search-results-card-boxed.png?fit=max\&auto=format\&n=vMCWPL7hzLnycFmk\&q=85\&s=0313f065f30f7b803d7dd004f6b3a749) > > ![Configure search results Inline Analytics](https://mintcdn.com/lucidworks/vMCWPL7hzLnycFmk/assets/images/lw-platform/commerce-studio/lw-cs-settings-search-results1-metrics-boxed.png?fit=max\&auto=format\&n=vMCWPL7hzLnycFmk\&q=85\&s=746c36e22f4da3482630e155b889944e) > > > [!NOTE] > > > > IMPORTANT: When you select these options, they only display on the Preview result card in Commerce Studio Settings. To select metrics to display on search result cards in Commerce Studio Editor, you must navigate to Commerce Studio Editor > Preview Settings > Metrics and select metrics options. For detailed information, see [Commerce Studio Editor Impressions metrics](/docs/lw-platform/lw-cs/cstudio-editor#impressions-metrics). ## Category The **Category** field you select is the name of the Fusion Solr field that contains indexed values you use to categorize search results. The Solr field is populated during Fusion indexing using the connector field mapping or an index pipeline stage configured with Field Mapping, JSON, or Script. The field name can be any Solr field such as `title_s` or `category_s`. For a Solr field with multiple values, the field has a `ss` at the end. For example, `title_ss` or `categories_ss`. The category values indexed in this field can be selected in the Commerce Studio Editor Conditions Manager, and apply to all of the following Editor features: * Display category-specific results to users * Mark specific rules that apply to that category and not the entire site * Display search metrics for only the selected category > **Guidelines and best practices for categories** > > These are the guidelines and best practices to consider when selecting the Solr field to use. > > * Use a dedicated string field that is a stable canonical value that reflects a category ID or a normalized breadcrumb path. Do not use a raw display label, an analyzed text field, or a free-text field. > > The Commerce Studio Editor's **Category** condition entered in the Condition Manager matches the literal indexed value, so exact matching is required. For example, in a B2B organization, category names may be updated to match procurement terminology or regulatory standards, so the underlying IDs should remain stable even when display labels change. > > * The field must be multivalued if items can belong to more than one category, for example, `categories_ss`. > > For example, a B2C product like a wool running jacket might belong to Running, Outerwear, and Sale simultaneously. In a B2B organization, a part might appear under both a product-type tree and an industry-application tree. And a knowledge article might be tagged under both a department and a content type. > > > [!WARNING] > > > > IMPORTANT: A single-valued field drops secondary category assignments, breaking both rules and facet counts. > > * In the Facet Fields section of the query pipeline, add the field to make category-level filtering available to users and drive Commerce Studio's per-category product-performance metrics. > > * For hierarchical categories where documents belong to a multi-level taxonomy, you need rules and facets to work at any level of that tree. For example, Electronics > Computers > Laptops. > > For this type of multi-level taxonomy, use a depth-prefix convention on a multivalued ancestor-path field, indexing each level as a separate value: > > * 0/Electronics > * 1/Electronics/Computers > * 2/Electronics/Computers/Laptops > > This lets Solr use facet prefix queries to retrieve only nodes at a given depth, and enables breadcrumb navigation and parent-child drill-down in your UI. Rules scoped to a parent node, such as Electronics, automatically apply to all child nodes. > **Configure a Fusion pipeline for categories** > > To configure a Fusion pipeline with categories that can be used in Commerce Studio, complete the following steps: > > **1. Add depth-prefixed values** > > In your index pipeline, add a JavaScript Index Stage or Field Mapper to generate the depth-prefixed values and write them to a multivalued string field. For example, `category_path_ss`. > > **2. Add leaf-level category** > > Add a second field for the leaf-level category for rules that target only the most specific node. For example, `category_leaf_s`. > > **3. Set facet field** > > Set `category_path_ss` as a facet field in your query pipeline in the Field Facet stage. > > **4. Set tree depth** > > In your query pipeline, set the `facet.prefix` parameter to `{depth}/` to retrieve only one level of the tree at a time. For example, `1/`. > > **5. Add optional companion field** > > Optionally, add a companion field such as `category_parents_ss`, listing only non-leaf nodes. When a facet value displays in this field, your UI renders an expand control. Otherwise it renders a leaf link, avoiding extra Solr round-trips. > **Configure categories in Commerce Studio** > > To configure categories used in Commerce Studio, complete the following steps: > > 1. In the **Category** field, select the identified Fusion Solr field name. > > > [!NOTE] > > > > This setting is per search profile. If you have multiple search profiles, configure the category field for each one that serves category pages. > > ![Configure categories](https://mintcdn.com/lucidworks/2b9yyNKfDTYuhcWc/assets/images/lw-platform/commerce-studio/lw-cs-settings-category.png?fit=max\&auto=format\&n=2b9yyNKfDTYuhcWc\&q=85\&s=2c9856734a7ad24010ddca8202ef3bfa) > > 2. Verify the values in the **Examples** section reflect the values you need for categories. > > > [!NOTE] > > > > When you select a value in the **Category** field, Commerce Studio accesses that Solr field using the read-only introspection endpoints granted to the `lwp_user` and `lwp_service_account` roles, and retrieves a sampling of values for the **Examples** field. It doesn't retrieve all of the field values. > > > > For the values that display in the Commerce Studio Editor screen, see [Use category conditions](/docs/lw-platform/lw-cs/cstudio-editor#use-category-conditions). ## Configure typeahead Typeahead, also known as autocomplete or autosuggest, is a feature that provides real-time query and phrase suggestions as you type in the Editor's search bar. In the Typeahead section, you can configure the fields to use for typeahead for this search profile. ![Configure typeahead](https://mintcdn.com/lucidworks/2b9yyNKfDTYuhcWc/assets/images/lw-platform/commerce-studio/lw-cs-settings-typeahead.png?fit=max\&auto=format\&n=2b9yyNKfDTYuhcWc\&q=85\&s=478598cbaa938a93ac5c46cb93709f7c) * To add a field, click the button. * To change a field, click the field and type to search for another one. * To change a field's display style, click the dropdown and select the style that best matches the field's data type. > [!NOTE] > > The Commerce Studio Settings Typeahead feature is for internal use in Commerce Studio. This is different than the [Lucidworks Platform Core Settings Typeahead feature](/docs/lw-platform/lw-core/sites-typeahead), which is where typeahead options for customer queries is configured. # Commerce Studio versus Predictive Merchandiser Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cstudio-versus-pm [old doc.lw link]: https://doc.lucidworks.com/lw-platform/cs/dndnds [localhost link]: http://localhost:3000/docs/lw-platform/lw-cs/cstudio-versus-pm [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-cs/cstudio-versus-pm This topic explains the differences and similarities between Commerce Studio and [Predictive Merchandiser](/docs/5/fusion/getting-data-out/curating-your-search-experience/predictive-merchandiser/overview) to make [migrating from Predictive Merchandiser to Commerce Studio](/docs/lw-platform/lw-cs/cs-migrate) easy. Both Predictive Merchandiser and Commerce Studio enable merchandisers, marketers, and product teams to manipulate search results for maximum impact. Commerce Studio has enhancements that make it easier and more efficient to use, optimizing your team's workflow. Contact Lucidworks for information about migrating from Predictive Merchandiser to Commerce Studio. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Feature overview This table summarizes the differences and similarities between Predictive Merchandiser (PM) and Commerce Studio (CS): | Feature | PM | CS | Details | | - | :-: | :-: | - | | Real-time dynamic preview | | | In Commerce Studio's [Editor](/docs/lw-platform/lw-cs/cstudio-editor), search results are updated instantly while you create and manage rules and query rewrites. | | Instant point-and-click rule creation | | | In Commerce Studio's Editor, you can hold the pointer over any item and click to create a new rule for it. No need to start a new task first; just point and click. | | Drag-and-drop rule creation | | | In Commerce Studio's Editor, you can drag and drop items to instantly create rules about their ordering. | | Integrated analytics | | | Commerce Studio displays metrics inline in the Editor to show you which products are performing or underperforming so you can take action with rules and rewrites. | | Conditions Manager | | | Commerce Studio's Conditions Manager lets you compare multiple queries and set specific conditions for your rules, such as a time range or tags. | | Ranking Insights | | | Commerce Studio's Ranking Insights feature shows you all of the ranking method and any rewrites that affect a query's results so you can adjust them as needed to achieve your goals. | | Execute panel | | | Commerce Studio's Execute panel displays all the of the rules associated with the given conditions (such as query, dates, and so on) right in the Editor, allowing you to view, add, and/or edit rules as needed. | | Rules Editor | | | In Commerce Studio, you can use either the [Rules UI](/docs/lw-platform/lw-cs/cstudio-rules) or the Editor. | | Query Rewrites Editor | | | Like Predictive Merchandiser, Commerce Studio provides a simple interface for [query rewrites](/docs/lw-platform/lw-cs/cstudio-query-rewrite). | | Customer interface simulation | | | Whereas Predictive Merchandiser uses templates and zones, Commerce Studio uses [preview settings](/docs/lw-platform/lw-cs/cstudio-settings) that you can customize for each search profile to simulate the pages on your customer-facing website. | | Integration with Fusion | | | Both products support [integrating with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/commerce-studio-integration). | ## Intro to Commerce Studio for Predictive Merchandiser clients Click below for a quick tour of Commerce Studio's Editor that shows you how it improves on Predictive Merchandiser's user experience with smoother, integrated controls: [Commerce Studio Editor demo for PM clients](https://app.supademo.com/embed/cmfhh5j07004zzd0jxrrhkdsi?embed_v=2\&utm_source=embed) ## Query rewrites All types of query rewrites are supported in both Predictive Merchandiser and Commerce Studio. When you [migrate to Commerce Studio](/docs/lw-platform/lw-cs/cs-migrate), all of your query rewrites are migrated too. The names of the query rewrite types differ slightly between the two products, as shown in this table: | Predictive Merchandiser rewrites | Commerce Studio rewrites | | - | - | | Head/Tail | Underperforming Queries | | Misspelling | Misspelling Detections | | Phrase | Phrase Detections | | Synonym | Synonym Detections | | Remove Words | Word Removal | See [Rewrites](/docs/lw-platform/lw-cs/cstudio-query-rewrite) for more details. ## Rule publication Like query rewrites, all of your existing rules are migrated when you migrate from Predictive Merchandiser to Commerce Studio. The possible values for a rule's publication status differ slightly between Predictive Merchandiser and Commerce Studio. This table shows the equivalent rule statuses between the two products: | Predictive Merchandiser rule status | Commerce Studio rule status | | - | - | | Published + Disabled | Draft | | Published + Enabled | Published | | Unpublished + Disabled | Draft | | Unpublished + Enabled | n/a | See [Rules](/docs/lw-platform/lw-cs/cstudio-rules) for more details. # Commerce Studio Source: https://doc.lucidworks.com/docs/lw-platform/lw-cs/overview [old doc.lw link]: https://doc.lucidworks.com/lw-platform/cs/nd39eb [localhost link]: http://localhost:3000/docs/lw-platform/lw-cs/overview [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-cs/overview Commerce Studio is Lucidworks’ next-generation merchandising studio, featuring an intuitive drag-and-drop, point-and-click editor. Designed and built for search teams, Commerce Studio lets business users tailor the search and browse experience through powerful rule building, visual merchandising, and more. To use Commerce Studio, you must complete all of the procedures described in the [Commerce Studio integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/commerce-studio-integration) topic. > [!TIP] > > This article describes features that are only available in certain packages. See [Lucidworks Feature Limited Availability](/docs/policies/feature-availability) for details, or reach out to your Lucidworks representative. > [!TIP] > > **FAQ: What if I'm using Predictive Merchandiser?** > > You can migrate Predictive Merchandiser data to Commerce Studio, including rules, query rewrites and template data. To compare the features of Predictive Merchandiser to Commerce Studio, see [Commerce Studio versus Predictive Merchandiser](/docs/lw-platform/lw-cs/cstudio-versus-pm). To migrate Predictive Merchandiser to Commerce Studio, see the [Migration guide](/docs/lw-platform/lw-cs/cs-migrate). > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Key features Commerce Studio provides several core features for crafting your search experience. ### Editor The [Editor](/docs/lw-platform/lw-cs/cstudio-editor) screen lets you visually merchandise results sets and simulate and test outcomes. The options on this screen let you: * Simulate search and browse experiences including rule execution and facet selection. * Review results based on rule and query rewrite configurations. * View ranking insights and analytics. * Preview field, variant, and metrics settings that display on each item in the catalog, including both standard and advanced grouping configurations. * View product performance metrics for each item in the result set. When you sign in to Lucidworks Platform, scroll to the Commerce Studio section, and then click the Commerce Studio instance to manage. The Editor screen is the default display. ![Home - Editor](https://mintcdn.com/lucidworks/67bW9Zw_7n8K4obu/assets/images/lw-platform/commerce-studio/lw-cs-home-editor.png?fit=max\&auto=format\&n=67bW9Zw_7n8K4obu\&q=85\&s=7743070b46b9c165e0784099f6426d83) For more information, see [Editor](/docs/lw-platform/lw-cs/cstudio-editor). ### Rules The [Rules](/docs/lw-platform/lw-cs/cstudio-rules) screen lets you easily and intuitively manage your merchandising rules. You can create conditional rules based on queries, durations, and categories. The rules affect the order products display in search results. The options on this screen let you pin, boost, bury, and block specific items in your catalog. You can also set facets, redirect customers to another page on your site, and more. The people in your organization who would create and edit rules include the following personnel: * Customer Experience Manager * Product Manager * Merchandiser For more information about user roles, see [Who is Commerce Studio for?](#who-is-commerce-studio-for) From the Commerce Studio screen, click **Rules** to display the screen. For example: ![Commerce Studio Rules main screen](https://mintcdn.com/lucidworks/2b9yyNKfDTYuhcWc/assets/images/lw-platform/commerce-studio/lw-cs-rules-main.png?fit=max\&auto=format\&n=2b9yyNKfDTYuhcWc\&q=85\&s=fc900aa6bd3ea6cc567ceeaf9a5814ea) For more information, see [Rules](/docs/lw-platform/lw-cs/cstudio-rules). ### Rewrites The [Rewrites](/docs/lw-platform/lw-cs/cstudio-query-rewrite) screen lets you configure rules to improve the query and generate more relevant results. In this option, you can: * Replace and improve less relevant search terms in underperforming queries * Correct misspelled words * Rewrite phrases to match higher performing phrases * Specify synonyms * Remove unnecessary words The people in your organization who would rewrite queries include the following personnel: * Director of eCommerce * Customer Experience Manager * Product Manager * Merchandiser * Digital Marketer For more information about user roles, see [Who is Commerce Studio for?](#who-is-commerce-studio-for) From the Commerce Studio screen, click **Rewrites** to display the screen. For example: ![Commerce Studio Rewrites main screen](https://mintcdn.com/lucidworks/2b9yyNKfDTYuhcWc/assets/images/lw-platform/commerce-studio/lw-cs-rewrites-main.png?fit=max\&auto=format\&n=2b9yyNKfDTYuhcWc\&q=85\&s=88ae2f96aa137b8aab5b7f070c211879) For more information, see [Rewrites](/docs/lw-platform/lw-cs/cstudio-query-rewrite). ### Settings The [Settings](/docs/lw-platform/lw-cs/cstudio-settings) screen lets you customize the Editor's live preview to reflect how your website looks. The options on this screen let you add fields to display for each search profile and configure typeahead settings to closely match the layout and behavior of your frontend so you can simulate scenarios that test the effectiveness of your rules and query rewrites before you implement them in your live customer environment. From the Commerce Studio screen, click **Settings** to display the screen. The people in your organization who would configure the preview settings include the following personnel: * Director of eCommerce * Customer Experience Manager * Product Manager * Merchandiser * Digital Marketer For more information about user roles, see [Who is Commerce Studio for?](#who-is-commerce-studio-for) > [!NOTE] > > The Commerce Studio Settings Typeahead feature is for internal use in Commerce Studio. This is different than the [Lucidworks Platform Core Settings Typeahead feature](/docs/lw-platform/lw-core/sites-typeahead), which is where typeahead options for customer queries is configured. For more information, see [Settings](/docs/lw-platform/lw-cs/cstudio-settings). ### Technical requirements | Requirement | Commerce Studio | Analytics Studio | | - | - | - | | Fusion 5.9.8 or later\[1] | | \[2] | | Lucidworks Platform | | | | Signals data | \[3] | | | Signals beacon\[4] | \[5] | | * \[1]: Requires a Fusion or Lucidworks Search environment running Fusion 5.9.8 or later. * \[2]: Analytics Studio provides search analytics insights and can operate independently of Fusion. * \[3]: Commerce Studio does not require signals data, but key features like product analytics depend on it. * \[4]: Future support is planned for alternative signals data sources. * \[5]: Commerce Studio does not require signals data, but key features like product analytics depend on it. ## Who is Commerce Studio for? Commerce Studio is designed for business users and ecommerce teams, including directors of ecommerce, customer experience managers, product managers, merchandisers, and digital marketers. The ecommerce teams can use Commerce Studio to build search and browse experiences to drive relevant search results to end users, while leveraging robust review and publishing workflows. Depending on the size and structure of your organization, one person may cover several of these roles. > [!NOTE] > > To use Commerce Studio, you must be granted **Workspace Owner** permissions in a Lucidworks Platform environment. ### Director of Ecommerce Use Commerce Studio to help develop and execute the overall ecommerce strategy. This includes all aspects of the online shopping experience, from site performance and customer experience to search optimization and revenue generation. * Optimize the search and browse experience and identify areas for improvement. * Develop and implement search optimization strategies to drive organic traffic and achieve revenue goals. * Analyze customer data and behavior to identify current and emerging trends and preferences. * Optimize ecommerce operations for efficiency and cost-effectiveness. ### Customer Experience Manager Use Commerce Studio to ensure customers have a seamless and satisfying search-to-purchase experience. * Conduct user testing and research to understand customer preferences and pain points. * Implement changes to the search experience based on customer insights. * Analyze search data to understand customer intent and preferences. * Identify and address factors contributing to "no results found" queries (also known as "null results" queries). ### Product Manager Use Commerce Studio to oversee product assortment and strategy across all digital channels. Ensure that products are optimally positioned to maximize visibility, customer experience, and sales. * Develop strategies to ensure that products are easily discoverable by customers. * Strike a balance between promoting trending products and ensuring that evergreen products remain visible. * Monitor inventory levels and ensure that in-stock products are prominently displayed and out-of-stock products are buried or hidden. * Consider bundling or cross-selling to promote slow-moving items. ### Merchandiser Use Commerce Studio to oversee product merchandising across all digital storefronts. Ensure that products are effectively positioned to maximize sales and conversions, drive customer engagement, and maintain brand consistency. * Develop and implement merchandising strategies to increase product visibility and discoverability on the website. * Strategically place products on the website to maximize sales and conversions. * Develop and execute merchandising plans for seasonal promotions. * Monitor the performance of seasonal promotions and make necessary adjustments to optimize results. ### Digital Marketer Use Commerce Studio to drive traffic to the site through marketing strategies. Ensure that digital marketing campaigns align with search results and maximize return on marketing campaigns align with search results and maximize return on ad spend. * Develop marketing campaigns that align with product launches or promotions. * Optimize product pages and website content for relevant keywords to ensure that promotions and new products appear prominently in search results. * Monitor and adjust strategies to maximize visibility during promotional periods. ### Data Analyst Use Commerce Studio to analyze search data and customer behavior. Uncover valuable insights that influence the merchandising strategies of the team. * Track and analyze key search metrics. * Identify areas of strength and weakness in search performance. * Recommend data-driven merchandising strategies. * Monitor performance over time to adjust strategies and recommendations. # Authentication API Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/authentication-api [old doc.lw link]: https://doc.lucidworks.com/lw-platform/ai/oa96k5 [localhost link]: http://localhost:3000/docs/lw-platform/lw-platform/authentication-api [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-platform/authentication-api The Authentication API authenticates users to use Lucidworks Platform APIs, including the [Lucidworks AI APIs](/docs/lw-platform/lw-ai/lw-ai-apis/overview) and [Commerce Studio Rules and Rewrites API](/docs/lw-platform/lw-cs/cs-rules-rewrites-api). The single endpoint generates an access token to use in future API requests. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Token guidelines and behavior * Lucidworks uses OAuth 2.0 to authenticate your credentials. * Tokens generated by the Authentication API are [Java Web tokens (JWT) tokens](https://jwt.io/). * Every token generated is active for 3600 seconds before it expires. After that token expires, API requests attempting to use the token fail and generate an HTTP status `401 Unauthorized` error. * You can generate a new token at any time. To avoid authorization failures, generate a new token before the current token expires. For example, generate a new token five minutes before the current token expires. > [!NOTE] > > To calculate the token expiration time, Base64 decode the JWT and review the `exp` field, which contains the expiration time in seconds since the Unix epoch. ## Authentication scope You must specify one or more values for the `scope` of each authentication request. The values depend on which API you use: | Scope | Used For | | - | - | | `machinelearning.predict` | Use Case API, Prediction API, Async Prediction API, and Async Chunking API | | `commercestudio.rules` | Commerce Studio rule operations (create, read, update, delete rules) | | `commercestudio.rewrites` | Commerce Studio query rewrite operations (create, read, update, delete rewrites) | > [!WARNING] > > Because the Use Case API, Prediction API, Async Prediction API, and Async Chunking API use the `machinelearning.predict` scope, if you request a new token with that scope, it deletes the existing token, so all of the APIs are affected. > You need to manage token regeneration for those APIs to run successfully. ## Fetch the access token > **Fetch an access token** > > **1. Locate your client ID and secret** > > Where you find the client ID and secret depends on which API you're using: > > * For [Lucidworks AI APIs](/docs/lw-platform/lw-ai/lw-ai-apis/overview), go to **Models** > **Integrations** and click your integration, then copy the **Client ID** and **Client Secret**. [Learn more about Lucidworks AI integrations](/docs/lw-platform/lw-ai/integrations). > > * For [Commerce Studio APIs](/docs/lw-platform/lw-cs/cs-rules-rewrites-api), go to **Settings** > **Service Accounts** and click your service account, then copy the **Client ID** and **Client Secret**. [Learn how to create a service account](/docs/lw-platform/lw-cs/cs-rules-rewrites-api#create-a-service-account). > > **2. Compose your request** > > Send your access token request to the authentication endpoint. > > The request uses basic authentication, where your base64-encoded client ID is your username and your base64-encoded client secret is your password. > Some clients perform the encoding automatically; if not, you can use the `base64` command-line utility, like this: > > ```bash theme={"dark"} > echo -n "CLIENT_ID:CLIENT_SECRET" | base64 > ``` > > Compose your request like this: > > ```bash theme={"dark"} > curl --request POST \ > --url 'https://identity.lucidworks.com/oauth2/ausao8uveaPmyhv0v357/v1/token?scope=API_SCOPE&grant_type=client_credentials' \ > --header 'Accept: application/json' \ > --header 'Authorization: Basic [CLIENT_ID:CLIENT_SECRET_BASE64]' \ > --header 'Cache-Control: no-cache' \ > --header 'Content-Type: application/x-www-form-urlencoded' > ``` > > Set the `scope` query parameter to the value for your API, as listed in [Authentication scope](#authentication-scope). > > **3. Fetch the access token** > > A successful request returns: > > ```json theme={"dark"} > { > "token_type": "Bearer", > "expires_in": 3600, > "access_token": "ACCESS_TOKEN", > "scope": "API_SCOPE" > } > ``` > > Copy the value of the `access_token` key and use it for API authentication. > > **4. Refresh your token every 60 minutes** > > API access tokens expire after 60 minutes. > > > [!WARNING] > > > > Once you request a new token, the previous one is deleted *even if it has not yet expired*. > > All subsequent API calls must use the new token. # Indexes Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/indexes The Indexes screen in Lucidworks Platform is where you can view your Fusion instances and perform promotions between environments. For Lucidworks Search clients, Lucidworks sets up and configure Fusion integrations for Lucidworks Platform. Self-hosted Fusion clients must set up [Fusion integrations](/docs/lw-platform/lw-platform/settings/fusion-integrations/overview) to view their Fusion instances here. Navigate to the megamenu and click **Indexes** to display the screen. ![Fusion instances](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/fusion/lw-platform-fusion-instances.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=afbb15bd2fc5135785ae1b828ee86619) > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Fusion instances The Fusion Instances tab displays by default, indicating if the deployment is self-hosted or Lucidworks Search and the environment such as Dev, Staging, or Prod. Using multiple Fusion environments lets you to try out new features, test configurations, and stage changes before pushing them into production. Making your changes in a Fusion environment for developers allows your team to test any changes thoroughly and make sure everything works as expected before promoting to an environment where more people, including your end users, can view the changes. These environments protect your website from a situation where a simple configuration error may affect your users, security, and operational goals. ### Accessing Lucidworks Search instances If you're using [Lucidworks Search](/docs/lucidworks-search/overview), you can access Fusion instances using SSO directly from Lucidworks Platform. Click **Managed** on a Fusion instance card to authenticate automatically. ![Managed button on a Fusion instances card](https://mintcdn.com/lucidworks/sM1ZkypaV6Y04faJ/assets/images/lw-platform/indexes-managed.png?fit=max\&auto=format\&n=sM1ZkypaV6Y04faJ\&q=85\&s=8865493011337eb37b263063c8c285db) If you need elevated access to perform administrative tasks in an instance of Lucidworks Search, request role elevation from Lucidworks Support or your Customer Success Manager. After the role is granted, log in again with Lucidworks Platform to activate your new permissions. ### Accessing Grafana metrics If you're using Lucidworks Search, you can access Grafana monitoring using SSO from Lucidworks Platform. Click the three dots on your Fusion instance card and select **View Metrics** to access your [Customer Dashboard](/docs/lucidworks-search/08-administration/monitoring/lucidworks-search/grafana-customer-dashboard-managed). ![View Metrics item under the three dots on a Fusion instances card](https://mintcdn.com/lucidworks/sM1ZkypaV6Y04faJ/assets/images/lw-platform/indexes-viewmetrics.png?fit=max\&auto=format\&n=sM1ZkypaV6Y04faJ\&q=85\&s=518afea8271d9c8848fe14370327f170) ## Configuration promotion This feature is available to both self-hosted and Lucidworks Search clients using Fusion 5.9.8 or later. The Configuration Promotion tool uses a GitHub configuration for every Fusion instance you want to manage. > [!NOTE] > > To use this feature, self-hosted Fusion clients must set up > [ConfigSync](/docs/5/fusion/operations/config-sync/overview) and complete all of the procedures described in the > [Configuration Promotion tool integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/configuration-promotion-integration) topic. ### Create and manage promotions To create and manage promotions, navigate to the Indexes screen and click the **Configuration Promotion** tab. ![Configuration promotion](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/fusion/lw-platform-configuration-promotion.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=a4272c082c80330175ab708e0777a247) #### Promotion statuses The Configuration Promotion table displays an Approval Status for each promotion request. The following statuses indicate the current state of a promotion: * **Creating Pull Request**: The system is generating the pull request for the promotion. * **Pending**: The pull request has been created and is awaiting review. * **Approved**: The promotion has been reviewed and approved for merging. * **Merged**: The changes have been successfully applied to the target environment. * **Withdrawn**: The promotion request has been canceled before merging. * **Broken**: The promotion encountered an error and cannot proceed. Contact your administrator for assistance. #### Start promotion For Lucidworks Search clients, promotion requests are reviewed by Lucidworks. You can track the approval status in the Configuration Promotion table. To promote an instance, click **Start Promotion**. 1. In the **Source** section, select the Fusion instance that contains the changes you want to promote. For example, if you’re promoting changes to a Staging environment, select your Dev environment. A file tree appears in the Source section that represents all the Fusion objects within the selected system. 2. Select the checkboxes for the files you want to promote into the target instance. > [!NOTE] > > Some files are restricted and cannot be selected for promotion. 3. In the **Target** section, select the Fusion instance where the changes will be promoted and then verify your selection. ![Request promotion](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/fusion/lw-platform-request-promotion.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=2fa775695d79a9320af302c12bc7d39b) 4. Click **Request Promotion**. On the Configuration Promotion page, a new promotion appears with an Approval Status of `Creating Pull Request`. When the Approval Status changes to `Pending`, the pull request has been created and is ready to be reviewed. #### Withdraw promotion To cancel a promotion request that hasn’t been merged yet, click the request to display the Details screen and then click **Withdraw Promotion**. ![Withdraw promotion](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/fusion/lw-platform-withdraw-promotion.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=1a342958922f99c175f6d56cf99ef366) # Platform Features Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/overview Lucidworks Platform [old doc.lw link]: https//doc.lucidworks.com/lw-platform/platform/rcwjfo [localhost link]: http://localhost:3000/docs/lw-platform/lw-platform/overview [mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-platform/overview Lucidworks Platform connects everything behind the scenes so your team can focus on what drives value: smarter experiences and better outcomes. Seamlessly integrated with Fusion, it provides powerful, no-code tools like [Lucidworks AI](/docs/lw-platform/lw-ai/overview), [Commerce Studio](/docs/lw-platform/lw-cs/overview), [Analytics Studio](/docs/lw-platform/lw-analytics/overview), and [Agent Studio](/docs/lw-platform/lw-agent-studio/overview) that let merchandisers, analysts, and AI innovators launch and optimize high-converting experiences with speed and confidence. Click your use case below to see examples of how you can enhance the search experience using Lucidworks Platform: **Business-to-Consumer** * **Commerce Studio:** Boost conversion rates by giving merchandisers no-code tools to fine-tune product rankings, promotions, and rules based on real-time shopper behavior. * **Analytics Studio:** Identify underperforming queries and high-value trends to optimize search and category experiences for maximum revenue impact. * **Agent Studio:** Power AI-driven support that delivers faster, more accurate answers by training agents on semantically chunked product and help content. * **Lucidworks AI:** Deploy scalable, cloud-hosted AI models that personalize search results, recommendations, and content based on user intent and behavior—without the infrastructure overhead. **Business-to-Business** * **Commerce Studio:** Customize product visibility and ranking by buyer type, region, or industry to better serve complex purchase journeys. * **Analytics Studio:** Analyze buyer behavior and search trends to improve lead qualification, refine content strategy, and increase deal velocity. * **Agent Studio:** Create AI agents that surface relevant specs, compliance data, and product insights from complex content libraries so buyers can verify requirements faster. * **Lucidworks AI:** Centralize control of AI model lifecycles for industrial-scale deployments—enabling more accurate relevance, faster updates, and streamlined governance across product catalogs and document repositories. **Knowledge Management** * **Commerce Studio:** Organize and prioritize knowledge artifacts so users and partners can access the most relevant information quickly and confidently. * **Analytics Studio:** Uncover content gaps and measure knowledge findability to continuously improve documentation and training resources. * **Agent Studio:** Deliver context-aware, role-specific answers with AI agents trained on semantically segmented internal knowledge, driving faster onboarding and support. * **Lucidworks AI:** Scale intelligent search and question-answering capabilities across vast corpora by managing models, chunking, and vector indexing from one unified cloud interface. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Platform Home screen When you access Lucidworks Platform, the Home screen displays: ![Lucidworks Platform Home screen](https://mintcdn.com/lucidworks/7X-cEH3Wf_j_zVZI/assets/images/lw-platform/platform-homepage.png?fit=max\&auto=format\&n=7X-cEH3Wf_j_zVZI\&q=85\&s=f8acc45e1b28092979cd8235f7f362a6) From the Home screen, you can access all of your sites, plus Lucidworks Platform products your organization has deployed, such as [Lucidworks AI](/docs/lw-platform/lw-ai/overview), [Commerce Studio](/docs/lw-platform/lw-cs/overview), [Analytics Studio](/docs/lw-platform/lw-analytics/overview), and [Agent Studio](/docs/lw-platform/lw-agent-studio/overview). ## Megamenu ![Lucidworks Platform megamenu](https://mintcdn.com/lucidworks/7X-cEH3Wf_j_zVZI/assets/images/lw-platform/lw-platform-megamenu-options.png?fit=max\&auto=format\&n=7X-cEH3Wf_j_zVZI\&q=85\&s=dab5ebab69f7a5d9f3c162dd0c8a8f69) The megamenu lets you access and manage global functions. It's available on every screen in Lucidworks Platform. Different options display based on Lucidworks Platform features and components your organization deploys. [Signals](/docs/lw-platform/lw-analytics/signals/overview) populate metrics in Analytics Studio. This option lets you view and manage the configuration for signals that collect and display customer interaction data from your website. The [Indexes](/docs/lw-platform/lw-platform/indexes) option lets you access and interact with Fusion instances that are registered with Lucidworks Platform. These include Fusion and Lucidworks search instances that provide links to the webpage and additional actions such as [performing promotions between environments](/docs/lw-platform/lw-platform/indexes). For example, after you test the configuration and performance of Lucidworks Platform in the Development (Dev) environment, you can promote it to Production (Prod) for your customers to use. **Models** is the option to manage integrations with Fusion and deploy pre-trained embedding models, custom embedding models, and generative AI models for [Lucidworks AI](/docs/lw-platform/lw-ai/overview). Under [Settings](/docs/lw-platform/lw-platform/settings/overview), you can [create and manage user accounts](/docs/lw-platform/lw-platform/settings/lw-users/overview) and [configure integrations between Fusion and Lucidworks Platform and its products](/docs/lw-platform/lw-platform/settings/fusion-integrations/overview). ## Feature compatibility and availability The table below lists the available Lucidworks Platform offerings with their dependencies and licensing requirements. | Feature | Dependency | | - | - | | Lucidworks AI | Fusion or Lucidworks Search 5.9.5 or later | | Lucidworks Platform | Fusion or Lucidworks Search 5.9.5 or later | | Neural Hybrid Search with Lucidworks AI | Fusion or Lucidworks Search 5.9.5 or later | | Neural Hybrid Search with Seldon | Fusion or Lucidworks Search 5.9.5 or later | | Enterprise SSO | Fusion or Lucidworks Search 5.9.5 or later | | Commerce Studio | Fusion or Lucidworks Search 5.9.8 or later | | Cloud Signal Storage | Lucidworks Search 5.9.6 or later | | Signals beacon | | | Analytics Studio | Fusion or Lucidworks Search 5.9.8 or later. Also requires the Signals beacon or Signals API. | Contact Lucidworks for access to the features you need. ## Getting help You can open the Help Center anywhere in Lucidworks Platform to access resources from our Knowledge Services and Technical Support teams, plus announcements about the latest products and capabilities. [https://app.supademo.com/embed/cmhzk1xug012oqnb96sm2f7vw?embed\_v=2\&utm\_source=embed](https://app.supademo.com/embed/cmhzk1xug012oqnb96sm2f7vw?embed_v=2\&utm_source=embed) Ready for your first training module? Start here: > **[About Lucidworks Platform](https://academy.lucidworks.com/about-lucidworks-platform)** > > Learn about Lucidworks Platform in this free training course. # Rate limiting Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/rate-limiting Rate limiting is used to help control network traffic and performance based on configuration of the timing and repetition of requests allowed on the network. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio Lucidworks Platform employs rate limiting to: * Provide a reliable service and optimal network performance for client organizations. * Protect clients from exceeding contracted consumption quotas which could result in overage charges. Each of the Lucidworks Platform APIs uses a similar approach: * Rate limitations are specified in the Lucidworks contract for your organization. Typically, most of the simple operations that do not impact query time are set to a lower rate limit. APIs considered to be in the critical path for query performance use a separate, higher rate limit. * If the request rate to a particular API exceeds the relevant limit, the system generates the [HTTP 429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) error. To resolve the issue, Lucidworks recommends you retry the request by implementing an [exponential backoff pattern](https://en.wikipedia.org/wiki/Exponential_backoff). For more information, or to ask questions about your account related to rate limiting, contact [Lucidworks Support](https://support.lucidworks.com). # Commerce Studio integration with Fusion Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/settings/fusion-integrations/commerce-studio-integration This type of Fusion integration lets you connect self-hosted Fusion instances to Lucidworks Commerce Studio. If you want to migrate from Predictive Merchandiser to Commerce Studio, the information in this topic is used in coordination with the procedures described in [Migration guide from Predictive Merchandiser to Commerce Studio](/docs/lw-platform/lw-cs/cs-migrate). You must satisfy the [prerequisites](#prerequisites) and complete all of the procedures in the order described in this topic to implement Lucidworks Commerce Studio: 1. [Create a Commerce Studio integration with Fusion](#create-a-commerce-studio-integration-with-fusion) 2. [Create Fusion roles required for Commerce Studio](#create-fusion-roles-required-for-commerce-studio) 3. [Create a Fusion security JWT realm for Commerce Studio](#create-a-fusion-security-jwt-realm-for-commerce-studio) 4. [Create the lwp service account in the JWT realm](#create-the-lwp-service-account-in-the-jwt-realm) 5. [Verify Commerce Studio integration with Fusion](#verify-commerce-studio-integration-with-fusion) 6. [Create a Commerce Studio instance using the UI](#create-a-commerce-studio-instance-using-the-ui) > [!TIP] > > This topic is specific to integrating Lucidworks Platform with Fusion for the use of Commerce Studio. > > * To configure a general integration for Lucidworks Platform with Fusion, follow the procedures in [Fusion integrations](/docs/lw-platform/lw-platform/settings/fusion-integrations/overview). > * To configure an integration that uses the Lucidworks Configuration Promotion tool, follow the procedures in the [Configuration Promotion tool integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/configuration-promotion-integration) topic. > * For information about a Fusion integration with Lucidworks AI, see [Lucidworks AI integrations](/docs/lw-platform/lw-ai/integrations). > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Prerequisites To create an integration, you must have the following prerequisites in place: * Admin privileges to a self-hosted Fusion environment running Fusion 5.9.8 or later. * A Fusion application that contains usable data. * Workspace Owner permissions in a Lucidworks Platform environment. * Privileges to access and use Lucidworks Commerce Studio in a Lucidworks platform workspace. > [!NOTE] > > **Network access requirements:** Lucidworks Platform must be able to reach the Fusion API URL you provide. Your Fusion instance must also be able to reach the Lucidworks JWK endpoint (`https://api.lucidworks.com/customers/`) to retrieve JSON Web Key Sets during JWT authentication. This endpoint is hosted on a separate IP range from the Lucidworks Platform itself. To obtain the IP ranges to add to your network allowlist, or for help configuring proxy access through the Fusion API gateway, contact Lucidworks support. ## Create a Commerce Studio integration with Fusion Complete the following procedures to create an integration from Lucidworks Commerce Studio to Fusion. 1. Navigate to the megamenu and click **Settings > Fusion Integrations**. 2. Click **Connect New Fusion**. 3. In the **Name** field, enter a unique name for the integration. For example, `Lucidworks Demo Dev`. 4. In the **API URL** field, enter the URL of your Fusion instance. For example, `https://FUSION_INSTANCE.com`. Do not enter a path after `.com`. 5. In the **Environment** field, select the Fusion instance environment or use the default of **Development**. 6. Optional: Enter one or more descriptive **Tags** that differentiate multiple integrations. ![Connect New Fusion integration](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/integrations/lw-platform-integrations-connect-new-fusion.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=caf4bd41e27903af1bbc19cf52d927f0) 7. Do not enter values in any of the fields in the **GitHub** section. Values in these fields are only required to set up the [Configuration Promotion tool integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/configuration-promotion-integration). 8. Click **Add**. Lucidworks Platform sends a `GET /api` request to your Fusion API gateway to validate the connection. If that request cannot reach your Fusion instance, the integration will not be created. If the value in the **API URL** field is: * Not valid, the integration is not created, and it is not displayed on the Fusion Integrations screen. * Valid, the Instructions to Connect with Fusion screen displays: ![Connect with Fusion](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/integrations/lw-platform-integrations-connect-jwt-values.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=ede987ae8c2735b1792970d07abf14d4) 9. Copy both the **JWK Set URL** value and the **Issuer URL** value to a secure location. These values must be used to create the JWT realm and are not displayed again after you click **Close**. 10. Click **Close**. 11. Verify the new integration displays on the Fusion Integrations screen. > [!NOTE] > > To edit the integration, hold the pointer over the integration, click the pencil icon, enter the changes, and click **Save**. To delete the integration, hold the pointer over the integration and click the trash can icon. ## Create Fusion roles required for Commerce Studio 1. Sign in to your Fusion instance as an admin and click the Fusion application to connect with Commerce Studio. 2. Navigate to **System > Access Control > Roles** and click **Add Role**. 3. In the **Name** field, enter `lwp_user`. 4. In the **Permissions** field, enter: ```bash lines highlight={3-4} theme={"dark"} GET,PUT,DELETE,POST,HEAD:/query/experience-manager/** GET,POST:/query/* POST:/query/*/preview GET,POST,PUT:/query-pipelines/** GET:/suggestions/** GET:/solr/*/terms PUT,POST,GET:/apps/*/query-pipelines/** GET:/apps/*/query-profiles/** GET,PUT:/apps/* POST:/apps/*/query/** GET:/solr/*/admin/luke GET:/solr/** ``` Each permission grants the following access: * `GET,PUT,DELETE,POST,HEAD:/query/experience-manager/**`: Commerce Studio query endpoints (read/write) for Commerce Studio UI and rule management. * `GET,POST:/query/*`: Query execution endpoints (read/write). `POST` sends query parameters in the request body and does not create or persist any configuration in Fusion. * `POST:/query/*/preview`: Rule preview endpoint (write) to view rule results without publishing them to production. * `GET,POST,PUT:/query-pipelines/**`: Query pipeline configuration (read/write) to manage pipeline stages used by Commerce Studio. * `GET:/suggestions/**`: Autocomplete and typeahead suggestions (read-only). * `GET:/solr/*/terms`: Solr term analysis (read-only) to view field values and vocabulary. * `PUT,POST,GET:/apps/*/query-pipelines/**`: Application-scoped query pipeline management (read/write) to manage app-specific pipeline operations. * `GET:/apps/*/query-profiles/**`: Query profiles (read-only) to view search configuration profiles. * `GET,PUT:/apps/*`: Fusion application settings (read/write) to view and update app metadata. * `POST:/apps/*/query/**`: Run queries (write) against a specified app's query profile without modifying the app. * `GET:/solr/*/admin/luke`: Solr index schema inspection (read-only) used to view available fields. * `GET:/solr/**`: General Solr read access (read-only). > [!TIP] > > Beginning with Fusion 5.9.15, all Commerce Studio integrations must have the `POST:/query/*/preview` and `GET,POST,PUT:/query-pipelines/**` permissions assigned to both the `lwp_user` and `lwp_service_account` roles in Fusion. This role does not require any UI permissions, so you do not have to select any values in the **UI Permissions** field. 5. In the **Description** field, enter role information. For example, "The lwp\_user account is required to access and use Commerce Studio. It is a super user account, but does not include the ability to get, modify, or delete the `HEAD` section of the site." 6. Click **Save**. 7. Click **Add Role**. 8. In the **Name** field, enter `lwp_service_account`. 9. In the **Permissions** field, enter the following permissions. These permissions include most of the lwp\_user account permissions plus the privileges to migrate Fusion Predictive Merchandiser rewrites, rules, templates and zones. ```bash lines highlight={3-4} theme={"dark"} GET,PUT,DELETE,POST,HEAD:/query/experience-manager/** GET,POST:/query/* POST:/query/*/preview GET,POST,PUT:/query-pipelines/** GET:/suggestions/** GET:/solr/*/terms PUT,POST,GET:/apps/*/query-pipelines/** GET:/apps/*/query-profiles/** GET,PUT:/apps/* GET,DELETE,PATCH,PUT,POST,HEAD:/apps/*/query-rewrite/** GET,HEAD:/templating/** GET:/solr/*/admin/luke GET:/solr/** ``` The `lwp_service_account` role includes most `lwp_user` permissions plus the following additional permissions that are required to migrate Predictive Merchandiser to Commerce Studio: * `GET,DELETE,PATCH,PUT,POST,HEAD:/apps/*/query-rewrite/**`: Query rewrite rules (read/write) to migrate Predictive Merchandiser rewrites, rules, and zones to Commerce Studio. * `GET,HEAD:/templating/**`: Templating access (read-only) to access Predictive Merchandiser templates during migration. > [!TIP] > > Beginning with Fusion 5.9.15, all Commerce Studio integrations must have the `POST:/query/*/preview` and `GET,POST,PUT:/query-pipelines/**` permissions assigned to both the `lwp_user` and `lwp_service_account` roles in Fusion. This role does not require any UI permissions, so you do not have to select any values in the **UI Permissions** field. 10. In the **Description** field, enter role information. For example, "The lwp\_service\_account contains most of the lwp\_user permissions as well as the privileges to migrate Fusion Predictive Merchandiser components to Lucidworks Commerce Studio." 11. Click **Save**. > [!TIP] > > The `PUT,POST,GET:/apps/*/query-pipelines/**` permission reflects the requirement to assign all necessary query pipeline permissions to the `lwp_user` and `lwp_service_account` roles. An additional example is for configuring a Lucidworks AI Gateway integration, where you need to assign `POST:/your-account-name/`. ## Create a Fusion security JWT realm for Commerce Studio 1. Sign in to your Fusion instance as an admin and click the application in which you created the `lwp_user` and `lwp_service_account` accounts to use with Commerce Studio. 2. Navigate to **System > Access Control > Security Realms** and click **Add Security Realm**. 3. In the **Name** field, enter a unique connection name. For example, **Lucidworks Commerce Studio JWT realm**. 4. In the **Type** field, select **jwt**. 5. Set the checkboxes in the following configuration. * Select the **Enabled** checkbox. * Do not select the **Ephemeral Users** checkbox. * Select the **Auto-Create Users** checkbox. 6. In the **Roles** field, select `lwp_user`. 7. In the **JWT Issuer** field, paste the **Issuer URL** value generated in the [Create a Commerce Studio integration with Fusion](#create-a-commerce-studio-integration-with-fusion) procedure. 8. In the **JWK Set URL** field, paste the **JWKS URL** value generated in the [Create a Commerce Studio integration with Fusion](#create-a-commerce-studio-integration-with-fusion) procedure. 9. In the **JWK Set Timeout** field, enter a timeout value in milliseconds for retrieving the JWKS. * This field is required. * Minimum value: `500` ms (set higher for known network latency). 10. Do not enter values (default is blank) in any of the following fields: * **Signing Key** * **Groups Key** * **Groups Mapping** * **User ID Attribute** 11. Click **Save**. > [!NOTE] > > Self-hosted Fusion clients can also view the integration `ID`, `Issuer URL`, `JWKS URL`, and other integration details in **Settings > Fusion Integrations** when the existing integration is selected. For general information, see [Lucidworks Platform integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/overview). Integrations for Lucidworks Search clients are created and updated by Lucidworks. ## Create the lwp service account in the JWT realm 1. Sign in to your Fusion instance as an admin and click the application to be connected with Commerce Studio. 2. Navigate to **System > Access Control > Users** and click **Add User**. 3. In the **Realm** field, select the JWT realm you created in the [Create a Fusion security JWT realm for Commerce Studio](#create-a-fusion-security-jwt-realm-for-commerce-studio). 4. In the **Username** field, enter `lwp-service-account`. 5. In the **Roles** field, select the `lwp_service_account` role. 6. In the **Timezone** field, select the appropriate timezone for the user account. 7. Click **Create**. ## Verify Commerce Studio integration with Fusion When the Fusion security JWT realm is created, complete the following steps to verify the Fusion information is displayed. 1. Navigate to the megamenu and click **Settings > Fusion Integrations**. 2. Hold the pointer over the integration and click the pencil icon. 3. Verify the information is accurate. > [!NOTE] > > The information in the Instructions section must match the values in the **Additional URLs JWKS URL** and **Issuer URL** fields. ## Create a Commerce Studio instance using the UI > [!WARNING] > > Do not create a Commerce Studio instance using the UI if you are migrating data from Predictive Merchandiser into that Commerce Studio instance. Instead, you must create the [instance using the API](/docs/lw-platform/lw-cs/cs-migrate). 1. In Lucidworks Platform, navigate to **Commerce Studio** and click **Create New**. 2. In the **Name** field, enter a unique name for the Commerce Studio instance. 3. In the **Region** field, select the geographic region for the Commerce Studio instance. This cannot be changed after the instance is created. 4. In the **Fusion to Connect** field, select the Fusion integration instance that matches the **Name** field created in the [Create a Commerce Studio integration with Fusion](#create-a-commerce-studio-integration-with-fusion) procedure. 5. Optional: In the **Signal Store** field, select the location where the Commerce Studio signals are stored. This value is only required if you want to use Lucidworks Analytics. 6. In the **Fusion Application** field, enter Lucidworks Platform application that connects to your Fusion instance. 7. Click **Next** to confirm settings, and then **Next** to create the instance. > [!NOTE] > > Data from the Fusion app is sent to Commerce Studio so you can create rules and refine the search experience. You can only connect one instance of Commerce Studio to a Fusion app. You cannot create multiple instances of Commerce Studio using the same Fusion app. > [!WARNING] > > 1. Commerce Studio exclusively manages `APP_NAME_query_rewrite_staging_em` and `APP_NAME_query_rewrite_em`. Do not manually add, edit, or delete documents in these collections. > 2. Commerce Studio reflects rules stored in its own platform database. Deleting documents from these Fusion Solr collections does not delete the corresponding rules in Commerce Studio. The collections will re-sync the next time Commerce Studio writes rules. > 3. Custom tooling built against these collections is not supported. ## Troubleshooting These errors may occur when Commerce Studio communicates with Fusion. When an error response includes a `fusionErrorMessage` field, use the message contents to identify the cause. > **400 error** > > The Commerce Studio instance status in Fusion may have been removed or disabled. > Manually set the status back to `READY` (if in preview mode) or `CONNECTED` (if already live). > **401 or 403 error** > > The JWT security realm used by Commerce Studio is not configured correctly. > Verify that the JWT realm is configured as described in [Create a Fusion security JWT realm for Commerce Studio](#create-a-fusion-security-jwt-realm-for-commerce-studio). > > If the realm configuration is correct, an expired JWT may be reaching Fusion. > Contact [Lucidworks support](https://lucidworks.com/support/). > > > [!NOTE] > > > > In some network environments, a JWT realm misconfiguration, particularly when Fusion cannot reach the JWKS endpoint, can surface as a 500 error rather than a 401 or 403. > > If you are investigating a 500 error and cluster health appears normal, also check the JWT realm configuration and network egress to the JWKS endpoint. > **500 or an unexpected response error** > > This typically indicates a problem with the Fusion instance itself. > Check the details of the returned error response to determine the cause: > > * **"Could not find a healthy node"** — The Fusion cluster cannot reach a healthy Solr node. Contact your Fusion instance administrator or [Lucidworks support](https://lucidworks.com/support/). > * **"Connection reset", "interrupted", or "timed out"** — The Fusion cluster may be overloaded or have a configuration issue causing slow responses. Contact your Fusion instance administrator. > * **JWT realm / JWKS endpoint unreachable** — If Fusion cannot reach the Lucidworks JWKS endpoint, for example, due to a firewall or proxy blocking egress, it fails to retrieve JWT signing keys and may return a 500 to Commerce Studio instead of a 401 or 403. Check egress rules, proxy configuration, and the JWT realm setup even when the error is a 500. See [network access requirements](#prerequisites) and the JWT realm configuration steps. # Configuration Promotion tool integration with Fusion Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/settings/fusion-integrations/configuration-promotion-integration This type of Fusion integration lets you connect self-hosted Fusion instances to the Lucidworks Configuration Promotion tool. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Use cases Configuration Promotion connects Fusion to a Git-backed promotion flow so you can version, review, and safely move configuration changes to pipelines, schemas, and rules from development to staging to production. It standardizes releases with approvals and audit trails, reducing risk while speeding up delivery. ### B2B use case Configuration Promotion adds a controlled, auditable path for repeatable, low-risk releases. For example, support and knowledge teams can reliably promote new index pipelines and security configurations after a pull request is approved. ### B2C use case For consumer search applications, Configuration Promotion shortens time-to-market by enforcing controlled promotions of relevancy rules, pipelines, and schemas across environments. For example, merchandising teams can test ranking tweaks in staging and promote them safely to production during a release window, following the same GitHub checks every time. > [!TIP] > > This topic is specific to integrating the Lucidworks Platform with Fusion for the use of the Configuration Promotion tool. > > * To configure a general integration for Lucidworks Platform with Fusion, follow the procedures in [Fusion integrations](/docs/lw-platform/lw-platform/settings/fusion-integrations/overview). > * To configure an integration that uses Lucidworks Commerce Studio, follow the procedures in the [Commerce Studio integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/commerce-studio-integration) topic. > * For information about a Fusion integration with Lucidworks AI, see [Lucidworks AI integrations](/docs/lw-platform/lw-ai/integrations). ## Prerequisites To create an integration, you must have the following prerequisites in place: * Admin privileges to a self-hosted Fusion environment running Fusion 5.9.8 or later. * A Fusion application that contains usable data. * Workspace Owner permissions in a Lucidworks Platform environment. You must complete all of the procedures in the order described in this topic to implement the Lucidworks Configuration Promotion tool. 1. [Create a GitHub token for configuration promotion](#create-a-github-token-for-configuration-promotion) 2. [Set up GitHub branch protection (optional)](#set-up-github-branch-protection-optional) 3. [Configure the integration](#configure-the-integration) 4. [Create a Fusion security JWT realm](#create-a-fusion-security-jwt-realm) 5. [Verify the Configuration Promotion tool integration with Fusion](#verify-the-configuration-promotion-tool-integration-with-fusion) ## Create a GitHub token for configuration promotion To set up the Configuration Promotion tool, you must generate a GitHub token. 1. Sign in to GitHub with an account that has access to the integrated systems repository. 2. In GitHub, click your profile icon, and then click **Settings**. 3. Navigate to **Developer Settings > Personal Access Tokens > Tokens (classic)**. 4. Click **Generate new token** and then select **Generate new token (classic)**. 5. In the **Note** field, enter details about the token. 6. In the **Expiration** field, select the period of time the token is active. Lucidworks recommends configuring a long duration in line with your organization’s security practices. You must generate and configure a new token for your Fusion integration every time your token expires. 7. In the **Select scopes** section, select the **repo** checkbox. This ensures the token has all required permissions. 8. Click **Generate token**. 9. Copy the generated token and save it in a secure location. > [!NOTE] > > Your GitHub organization may need to authorize your token. For more information, see [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). ## Set up GitHub branch protection (optional) Lucidworks recommends enabling GitHub branch protection for your production (PROD) branch. This protects a branch with requested changes from being promoted until that request has been reviewed. To configure branch protections, see [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). The configuration promotion tool looks at GitHub to see if the branch is ready to merge. The tool can integrate with any GitHub automations that change the merge-ready status of the branch. ## Configure the integration To create an integration for the Lucidworks Configuration Promotion tool with Fusion, navigate to the megamenu and click **Settings > Fusion Integrations**. 1. Click **Connect New Fusion**. 2. In the **Name** field, enter a unique name for the integration. For example, `Lucidworks Demo Dev`. 3. In the **API URL** field, enter the URL of your Fusion instance. For example, `https://FUSION_INSTANCE.com`. Do not enter a path after `.com`. 4. In the **Environment** field, select the Fusion instance environment or use the default of **Development**. 5. Optional: Enter one or more descriptive **Tags** that differentiate multiple integrations. ![Connect New Fusion integration](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/integrations/lw-platform-integrations-connect-new-fusion.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=caf4bd41e27903af1bbc19cf52d927f0) 6. All fields in the **GitHub** section are required if you’re setting up the Configuration Promotion tool. 1. In the **GitHub Branch URL** field, enter the URL from GitHub for your self-hosted Fusion install. The format is `https://github.com/ORGANIZATION_NAME/REPOSITORY_NAME/tree/BRANCH_NAME`. For example, `https://github.com/company_name/fusion_install/tree/lucidworks_demo_dev`. 2. In the **GitHub Token** field, enter the [personal access token](#create-a-github-token-for-configuration-promotion) granted privileges to the GitHub organization linked to your self-hosted Fusion install. 7. Click the **Enable Fusion Configuration Promotion** field to **ON** to allow files or instances to be promoted from development to a staging or production environment. ![GitHub information](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/integrations/lw-platform-integrations-github-info.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=3c7e1e9a2d36df7dc884a68eeb7f6738) 8. Click **Add**. If the value in the **API URL** field is: * Not valid, the integration is not created, and it is not displayed on the Fusion Integrations screen. * Valid, the Instructions to Connect with Fusion screen displays: ![Connect with Fusion](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/integrations/lw-platform-integrations-connect-jwt-values.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=ede987ae8c2735b1792970d07abf14d4) 9. Copy both the **JWK Set URL** value and the **Issuer URL** value to a secure location. These values must be used to [Create a Fusion security JWT realm](#create-a-fusion-security-jwt-realm). These values must be used to create the JWT realm and are not displayed again after you click **Close**. 10. Click **Close**. 11. Verify the new integration displays on the Fusion Integrations screen. > [!NOTE] > > To edit the integration, hold the pointer over the integration, click the pencil icon, enter the changes, and click **Save**. To delete the integration, hold the pointer over the integration and click the trash can icon. ## Create a Fusion security JWT realm To complete required fields in the integration, you must create a Fusion security realm. 1. Sign in to your Fusion instance as an admin and click the Fusion application to connect with the Lucidworks Configuration Promotion tool. 2. Navigate to **System > Access Control > Security Realms** and click **Add Security Realm**. 3. In the **Name** field, enter a unique connection name. For example, **Lucidworks Configuration Promotion tool JWT realm**. 4. In the **Type** field, select **jwt**. 5. Set the checkboxes in the following configuration. * Select the **Enabled** checkbox. * Do not select the **Ephemeral Users** checkbox. * Select the **Auto-Create Users** checkbox. 6. In the **Roles** field, select the roles that this realm provides after successfully authenticating a user by default. 7. In the **JWT Issuer** field, paste the **Issuer URL** value generated in the [Configure the integration](#configure-the-integration) procedure. 8. In the **JWK Set URL** field, paste the **JWKS URL** value generated in the [Configure the integration](#configure-the-integration) procedure. 9. Do not enter values (default is blank) in any of the following fields: * **Signing Key** * **Groups Key** * **Groups Mapping** * **User ID Attribute** 10. Click **Save**. ## Verify the Configuration Promotion tool integration with Fusion When the Fusion security JWT realm is created, complete the following steps to verify the Fusion information is displayed. 1. Navigate to the megamenu and click **Settings > Fusion Integrations**. 2. Hold the pointer over the integration and click the pencil icon. 3. Verify the information is accurate. > [!NOTE] > > The information in the Instructions section must match the values in the **Additional URLs JWKS URL** and **Issuer URL** fields. # Fusion Integrations Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/settings/fusion-integrations/overview The Fusion Integrations features lets you connect self-hosted Fusion instances to Lucidworks Platform features and other software to extend and enhance your workflows. This topic details how to create an integration between Lucidworks Platform and Fusion. You must satisfy the [prerequisites](#prerequisites) and complete the procedures in the order described in this topic: 1. [Create a Lucidworks Platform integration with Fusion](#create-a-lucidworks-platform-integration-with-fusion) 2. [Create a Fusion security JWT realm for Lucidworks Platform](#create-a-fusion-security-jwt-realm-for-lucidworks-platform) 3. [Verify the integration](#verify-the-integration) > [!TIP] > > This topic details the steps to configure a general integration for Lucidworks Platform with Fusion. > > * To configure an integration that uses the Lucidworks Configuration Promotion tool, follow the procedures in the [Configuration Promotion tool integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/configuration-promotion-integration) topic. > * To configure an integration that uses Lucidworks Commerce Studio, follow the procedures in the [Commerce Studio integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/commerce-studio-integration) topic. > * For information about a Fusion integration with Lucidworks AI, see [Lucidworks AI integrations](/docs/lw-platform/lw-ai/integrations). > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Prerequisites To create an integration between Lucidworks Platform and Fusion, you must have the following prerequisites in place: * Admin privileges to a self-hosted Fusion environment running Fusion 5.9.8 or later. * A Fusion application that contains usable data. * Workspace Owner permissions in a Lucidworks Platform environment. ## Create a Lucidworks Platform integration with Fusion Complete the following steps to create an integration from Lucidworks Platform to Fusion. 1. Navigate to the megamenu and click **Settings > Fusion Integrations**. 2. Click **Connect New Fusion**. 3. In the **Name** field, enter a unique name for the integration. For example, `Lucidworks Demo Dev`. 4. In the **API URL** field, enter the URL of your Fusion instance. For example, `https://FUSION_INSTANCE.com`. Do not enter a path after `.com`. 5. In the **Environment** field, select the Fusion instance environment or use the default of **Development**. 6. Optional: Enter one or more descriptive **Tags** that differentiate multiple integrations. ![Connect New Fusion integration](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/integrations/lw-platform-integrations-connect-new-fusion.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=caf4bd41e27903af1bbc19cf52d927f0) 7. Do not enter values in any of the fields in the **GitHub** section. Values in these fields are only required to set up the [Configuration Promotion tool integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/configuration-promotion-integration). 8. Click **Add**. If the value in the **API URL** field is: * Not valid, the integration is not created, and it is not displayed on the Fusion Integrations screen. * Valid, the Instructions to Connect with Fusion screen displays: ![Connect with Fusion](https://mintcdn.com/lucidworks/LWfoinT68um04ZwW/assets/images/lw-platform/integrations/lw-platform-integrations-connect-jwt-values.png?fit=max\&auto=format\&n=LWfoinT68um04ZwW\&q=85\&s=ede987ae8c2735b1792970d07abf14d4) 9. Copy both the **JWK Set URL** value and the **Issuer URL** value to a secure location. These values must be used to create the JWT realm. These values must be used to create the JWT realm and are not displayed again after you click **Close**. 10. Click **Close**. 11. Verify the new integration displays on the Fusion Integrations screen. > [!NOTE] > > To edit the integration, hold the pointer over the integration, click the pencil icon, enter the changes, and click **Save**. To delete the integration, hold the pointer over the integration and click the trash can icon. ## Create a Fusion security JWT realm for Lucidworks Platform To complete required fields in the integration, you must create a Fusion security realm. 1. Sign in to your Fusion instance as an admin and click the Fusion application to connect with Lucidworks Platform. 2. Navigate to **System > Access Control > Security Realms** and click **Add Security Realm**. 3. In the **Name** field, enter a unique connection name. For example, **Lucidworks Platform JWT realm**. 4. In the **Type** field, select **jwt**. 5. Set the checkboxes in the following configuration. * Select the **Enabled** checkbox. * Do not select the **Ephemeral Users** checkbox. * Select the **Auto-Create Users** checkbox. 6. In the **Roles** field, select the roles that this realm provides after successfully authenticating a user by default. 7. In the **JWT Issuer** field, paste the **Issuer URL** value generated in the [Create a Lucidworks Platform integration with Fusion](#create-a-lucidworks-platform-integration-with-fusion) procedure. 8. In the **JWK Set URL** field, paste the **JWKS URL** value generated in the [Create a Lucidworks Platform integration with Fusion](#create-a-lucidworks-platform-integration-with-fusion) procedure. 9. Do not enter values (default is blank) in any of the following fields: * **Signing Key** * **Groups Key** * **Groups Mapping** * **User ID Attribute** 10. Click **Save**. ## Verify the integration When the Fusion security JWT realm is created, complete the following steps to verify the Fusion information is displayed. 1. Navigate to the megamenu and click **Settings > Fusion Integrations**. 2. Hold the pointer over the integration and click the pencil icon. 3. Verify the information is accurate. > [!NOTE] > > The information in the Instructions section must match the values in the **Additional URLs JWKS URL** and **Issuer URL** fields. # Users and Provisioning Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/settings/lw-users/overview The Users and Provisioning screen lets you [invite workspace owners](#invite-workspace-owners) to use Lucidworks Platform. In addition, you can [create authentication that supports sign-on (SSO)](/docs/lw-platform/lw-platform/settings/lw-users/sso), which restricts user logins to specified email domains. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Users The Users screen displays all the users associated with your workspaces. To view a list of users, navigate to the megamenu and click **Settings > Users & Provisioning**. The name, status, date user was created, and email of each user displays. ![Users and Provisioning screen](https://mintcdn.com/lucidworks/NBLtyMOgD7g9MyhX/assets/images/lw-platform/users/lw-users-and-provisioning-workspace-owner.png?fit=max\&auto=format\&n=NBLtyMOgD7g9MyhX\&q=85\&s=19e08d7e37e2214026b5940ecb7c58b7) **User** **properties** **Name** `string` First and last name of the user. **Status** `string` Possible values: * **Active.** User has clicked the **Activate** link in the email and can access Lucidworks Platform as a workspace owner, which can manage the workspace and invite other users. * **Awaiting Activation.** User is invited, but has not clicked the **Activate** link in the email. * **Deleted.** User account has been deleted. * **Deprovisioned.** User account has been deactivated and cannot access Lucidworks Platform. * **Recovery.** User account was once deprovisioned, but has been recovered for future use. * **Password-expired.** User must create a new password to reactivate the account. **Created** `string` Date the invitation was created. **Email** `string` User’s email address. ### Invite workspace owners > [!NOTE] > > Only workspace owners for the specified workspace can invite users to that workspace. 1. Navigate to the megamenu and click **Settings > Users & Provisioning**. 2. Click **+ Invite** and enter the user’s information in the **First name**, **Last name**, and **Email** fields. Required fields are notated with an asterisk (\*). ![Invite usersh-lg-modal](https://mintcdn.com/lucidworks/NBLtyMOgD7g9MyhX/assets/images/lw-platform/users/invite-user-workspace-owner.png?fit=max\&auto=format\&n=NBLtyMOgD7g9MyhX\&q=85\&s=741c8bdcbd793b6a4e30bfa2585fa2db) 3. To email the user the invitation, click **Send Invite**. To exit without creating a user, click **Cancel**. 4. In the Users list, verify the status of the new user status is **Awaiting Activation**. > [!NOTE] > > When the user accepts the email invitation, the status displays as Active. If the user does not receive the email invitation in their inbox, ask them to look in the spam folder for an email from `no-reply@lucidworks.com`. If the invitation is not in their inbox or spam folder, verify the user's email information. If your troubleshooting efforts are unsuccessful, contact [Lucidworks Support](https://support.lucidworks.com). ### Edit or delete users To edit a user, click the entry for the user you want to edit. You can also click **View/Edit**. Workspace owners can also click **Delete User** to delete the user. ## Authentication using single-sign on The Authentication screen lets you configure a single sign-on (SSO) option, which supports the following features: * Restricts user logins to specified email domains * Uses your organization’s identity provider authentication method instead of Lucidworks' built-in authentication Workspace owners can configure SSO via OpenID Connect (OIDC) or Security Assertion Markup Language (SAML). For more information, see [Single sign-on authentication](/docs/lw-platform/lw-platform/settings/lw-users/sso). # Single sign-on authentication Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/settings/lw-users/sso Lucidworks Platform supports single sign-on (SSO), which restricts user logins to specified email domains and uses your organization’s identity provider authentication method instead of Lucidworks' built-in authentication. Workspace owners can configure SSO via [OpenID Connect (OIDC)](#oidc-authentication) or [Security Assertion Markup Language (SAML)](#saml-authentication). > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## OIDC Authentication [OIDC](https://openid.net/developers/how-connect-works/) is an authentication protocol based on the OAuth 2.0 framework, which uses HTTPS endpoints to retrieve user data. It uses JSON web tokens (JWT) to authenticate user identity data (also known as claims). Tokens are digitally signed and can also be encrypted. Complete all of the following procedures to configure OIDC authentication. ### Create users in Lucidworks Platform > [!TIP] > > **Prerequisites** > > 1. Users must be added to the Lucidworks Platform. > 2. Users must exist in your identity provider, and be enabled for the application you are using to connect with Lucidworks Platform. > 3. The user’s email address in your identity provider and Lucidworks Platform must match, including case. Some identity providers treat email addresses as case-sensitive, which can prevent a user from accessing Lucidworks Platform if the case doesn't match exactly. 1. Navigate to the megamenu and click **Settings > Users & Provisioning > Users**. 2. Verify all necessary users are listed, active, and their emails match their identity provider user counterparts. 3. If any users are missing, add the appropriate users by completing the steps in [invite workspace owners](/docs/lw-platform/lw-platform/settings/lw-users/overview#invite-workspace-owners). ### Create an OIDC application in your identity provider 1. Create a new OIDC application in your identity provider. Refer to your provider's documentation for detailed steps: * [Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) * [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-oidc-sso#configure-oidc-sso-for-custom-non-gallery-applications) * [Google Workspace](https://support.google.com/cloud/answer/6158849) 2. When creating the application, use the following settings: * **Sign-in method**: Select **OIDC**. * **Application type**: Select **Web Application**. * **Sign-in redirect URIs**: Leave this blank for now. You’ll configure it in a later step. * **Logout redirect URIs**: Remove all URIs. * **Controlled access**: Allow everyone in your organization to access the application. * **Access approval**: Disable any setting that grants users immediate access without admin approval. 3. After creating the application, copy the **Client ID** and the **Client Secret**, and save them in a secure location. > [!TIP] > > The **Client ID** and the **Client Secret** credentials are critical for OIDC communication and must be kept secure. 4. Assign at least one user and one admin to the application. These users must already exist in Lucidworks Platform. You must assign yourself as one of the users to be able to complete the authentication configuration. ### Create the Identity Provider in Lucidworks Platform 1. Navigate to the megamenu and click **Settings > Users & Provisioning > Authentication > OIDC**. 2. Enter values in the required fields: * **Email Domains**: Enter the list of domains you want to use as filter options, for example, `lucidworks.com`. > [!WARNING] > > Be careful not to lock yourself out at this step in the process. If you list a domain that you already use to log into Lucidworks Platform, and you don’t complete the rest of the steps listed here, then you will be prompted to log in via SSO the next time you log out, which won’t work. If you are unable to log into Lucidworks Platform, contact Support or your Lucidworks representative. * Enter the **Client ID** and **Client Secret** provided by your identity provider's OIDC application. * Enter the **Configuration URL** provided by your identity provider. > [!TIP] > > To get the full OIDC configuration URL, append `/.well-known/openid-configuration` to your Issuer URL. For example, if your issuer is `https://idp.example.com`, the full configuration URL would be: `https://idp.example.com/.well-known/openid-configuration` * Enter the **Issuer URL**, which identifies your identity provider's authorization server and is provided by your identity provider's OIDC application. * Enter the **Authorization URL** for the server that performs user authorization. * Enter the **Token URL** for the server where the authorization code is sent to obtain a user access token. * Enter the **User Info URL** for the server where the user profile attributes are stored and can be retrieved after authentication. * Enter the **JWKS URL**, which is the JSON Web Key Set that verifies signed JWT tokens, provided by your identity provider's OIDC application. 3. Click **Save**. 4. The Identity Provider process may take several minutes to complete. Once finished, the **URLs for IDP Configuration** display on the right side of the screen. Copy the **Redirect URL** and save it in a secure location. ### Configure the redirect URI in your identity provider 1. In your identity provider, navigate to the application you created for Lucidworks SSO. 2. Add the **Redirect URL** generated by Lucidworks Platform to the application's sign-in redirect URIs. 3. Save your changes. ### Test SSO functionality After configuring both Identity Provider and the application, test the integration by attempting to log into Lucidworks Platform with one of the users assigned to the application. If the configuration is successful, you are prompted to log in with your identity provider's authentication. ## SAML authentication [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) is an XML-based protocol that uses HTTP to authenticate and authorize user data. In a SAML workflow, Lucidworks Platform is the Relying Party (RP) that requests and receives SAML assertions from the identity provider. ### Create users in Lucidworks Platform > [!TIP] > > **Prerequisites** > > 1. Users must be added to the Lucidworks Platform. > 2. Users must exist in your identity provider, and be enabled for the application you are using to connect with Lucidworks Platform. > 3. The user’s email address in your identity provider and Lucidworks Platform must match, including case. Some identity providers treat email addresses as case-sensitive, which can prevent a user from accessing Lucidworks Platform if the case doesn't match exactly. 1. Navigate to the megamenu and click **Settings > Users & Provisioning > Users**. 2. Verify all necessary users are listed, active, and their emails match their identity provider user counterparts. 3. If any users are missing, add the appropriate users by completing the steps in [invite workspace owners](/docs/lw-platform/lw-platform/settings/lw-users/overview#invite-workspace-owners). ### Create a SAML application in your identity provider 1. Create a new SAML application in your identity provider. Refer to your provider's documentation for detailed steps: * [Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) * [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) * [Google Workspace](https://support.google.com/a/answer/6087519) 2. When creating the application, use the following settings: * **Sign-in method**: Select **SAML 2.0**. * **Single Sign On URL (ACS URL)**: Enter a placeholder URL for now. You’ll configure it in a later step. * **Audience URI (SP Entity ID)**: Enter a placeholder URL for now. You’ll configure it in a later step. * **Name ID Format**: Select the appropriate Name ID format. This is usually `EmailAddress`. * **Application username**: Choose how your identity provider should map the user’s application username. For example, their identity provider username or email address. 3. After creating the application, locate its metadata, copy the **Metadata URL**, and save it in a secure location. > [!TIP] > > The **Metadata URL** is critical for SAML communication and must be kept secure. 4. Assign at least one user and one admin to the application. These users must already exist in Lucidworks Platform. You must assign yourself as one of the users to be able to complete the authentication configuration. ### Create the Identity Provider in Lucidworks Platform 1. Navigate to the megamenu and click **Settings > Users & Provisioning > Authentication > SAML**. 2. Fill out required fields: * **Email Domains**: Enter the list of domains you want to filter by, for example, `\lucidworks.com`. > [!WARNING] > > Be careful not to lock yourself out at this step in the process. If you list a domain that you already use to log into Lucidworks Platform, and you don’t complete the rest of the steps listed here, then you will be prompted to log in via SSO the next time you log out, which won’t work. If you are unable to log into Lucidworks Platform, contact Support or your Lucidworks representative. * Enter the **Metadata URL** provided by your identity provider's SAML application. * Enter the **Issuer URL** that specifies which identity provider is used by SAML. This value is generated when the SAML application is created. * Enter the **Identity Provider SSO URL**, which is the single sign-on endpoint for users, and is provided by your identity provider's SAML application. * Paste the **Certificate** information, which is provided by your identity provider's SAML application and is used by the identity provider to sign SAML responses. 3. Click **Save**. 4. The Identity Provider process may take several minutes to complete. Once finished, the **URLs for IDP Configuration** display on the right side of the screen: * **Audience URI** * **Assertion Consumer Service URL** 5. Copy the URLs and save them in a secure location. ### Configure the application in your identity provider 1. In your identity provider, navigate to the application you created for Lucidworks SSO. 2. Update the application's SAML settings: * In **Single Sign On URL (ACS URL)** paste the **Assertion Consumer Service URL** generated by Lucidworks Platform. * In **Audience URI (SP Entity ID)** paste the **Audience URI** generated by Lucidworks Platform. 3. Optional: If your identity provider supports SAML attribute mapping, configure the following mappings to send additional user information to Lucidworks Platform: | | Name | Name Format | Value | | - | - | - | - | | **Email** | `email` | Unspecified | `user.email` | | **First Name** | `firstName` | Unspecified | `user.firstName` | | **Last Name** | `lastName` | Unspecified | `user.lastName` | | **Username** | `username` | Unspecified | `user.login` | 4. Save your changes. ### Test SSO functionality After configuring both Identity Provider and the application, test the integration by attempting to log into Lucidworks Platform with one of the users assigned to the application. If the configuration is successful, you are prompted to log in with your identity provider's authentication. # Settings Source: https://doc.lucidworks.com/docs/lw-platform/lw-platform/settings/overview The Settings options of Lucidworks Platform lets you: import from '/snippets/LwTemplate.jsx'; * Create and manage user accounts, including setting roles, permissions, and authentication for users in Lucidworks Platform. * Configure integrations that connect Fusion to Lucidworks Platform and other software to extend and enhance your workflows. To access the screen, navigate to the megamenu, click **Settings**. * To create and manage user accounts and user permissions, click **Users & Provisioning > Users**. For more information, see [Users and Provisioning](/docs/lw-platform/lw-platform/settings/lw-users/overview). * To configure single sign-on authentication, click **Users & Provisioning > Authentication**. For more information, see [Single sign-on authentication](/docs/lw-platform/lw-platform/settings/lw-users/sso). * To configure and manage Fusion integrations to Lucidworks Platform, Commerce Studio, and Analytics Studio, click **Fusion Integrations**. For more information, see * [Lucidworks Platform integrations with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/overview) * [Commerce Studio integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/commerce-studio-integration) * [Configuration Promotion tool integration with Fusion](/docs/lw-platform/lw-platform/settings/fusion-integrations/configuration-promotion-integration) For information about integrations between Lucidworks AI and Fusion, see [Lucidworks AI integrations](/docs/lw-platform/lw-ai/integrations). # Button Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/components/button Interactive or static button component for navigation or actions in UI Studio applications The Button component provides buttons that users can click or view for UI Studio applications. Use buttons to enable navigation to other pages or trigger actions like CSV data exports. You can style buttons with custom text and colors. ## Basic usage Add a button to your UI Studio page to create an interactive element for users. ![Basic Button component](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/ui-studio-button.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=b95f0480436037435f181f4f58232350) Basic Button component Enter descriptive label text for the button and apply formatting in the Button component Customize section. ## Best practices Use descriptive labels that clearly indicate the action. For example, **View details** or **Submit form**. Avoid vague labels such as **Click here**. ## Configuration properties **Label** `string` *required* Text displayed on the button. Keep this concise and action-oriented. **Action** `dropdown` *required* The action performed when the user clicks the button. **Action** **Link** `option` Navigation button with URL. The `Page Path` field contains the target URL. **Export** `option` Action button for CSV downloads. **Page Path** `string` URL path for navigation. Supports token syntax: `${TOKEN_NAME}` that is specified in the `Token Name` and `Field Name` fields. Examples: * `/home` * `/users/${userId}` * `/products/${productId}/details?tab=${activeTab}` **Open in New Tab** `boolean` (default: false) When enabled, the link specified in the `Page Path` field opens in a new browser tab. **Tokens** `group` Token settings for button navigation. **Tokens** **Token Name** `string` Unique name for the navigation token. **Field Name** `string` The field that contains the token used when the user clicks the button. **Font** `group` Typography settings for the text. **Properties** **Family** `dropdown` (default: Public Sans) Font typeface for the text. **Weight** `dropdown` (default: Regular) Font weight for the text. Options are Regular, Light, Bold, and Extra Bold. **Size** `number` (default: 14) Font size in pixels. Recommended ranges: * Body text: 14-16px. * Headings: 18-32px. * Small text: 12-13px. **Colors** `group` Color scheme for the button. **Properties** **Background** `color` (default: #ffffff) Background color of the button. **default** `#ffffff` **Text** `color` (default: #2C3136) Text color for the button label. Ensure sufficient contrast with background color. **default** `#2C3136` **Border** `color` (default: #D7DBDF) Outline color of the button. **default** `#D7DBDF` **Border Radius** `number` (default: 0) Border radius in pixels. Controls corner roundness. * `0` = Square corners * `4-8` = Subtle rounding * `20+` = Pill-shaped button # Facets Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/components/facets Interactive filtering component for refining search results by categories and attributes in UI Studio applications The Facets component in UI Studio provides interactive filters that allow users to refine search results by selecting categories, attributes, and values. Use facets to narrow down large datasets by criteria like manufacturer, category, price range, or any custom field from your data. > **[UI Studio: Crafting the Discovery Experience](https://academy.lucidworks.com/training/019fecaa-3fd4-721e-8985-bf28d235dd76/overview)** > > Learn how to configure the Results List with Grid or Document layouts, set up facets with human-legible field names, and enable search-within-results refinement. ## Basic usage Add a facets component to your UI Studio page to enable filtering capabilities. To build a minimal facets component, you must set a value for the Datastore field and a facet category to display. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/add-facets.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=99c08be5a277270ba2b2e55f5c11ff02) Facets component in the canvas If no facets are available for the provided datastore, the component displays an empty state message: "No facets found. Please try adjusting your search criteria." To add a facet, click the **+** next to the **Facets** selector. Facets display in a vertical list. ## Searchable facet values Enable search within facet values for categories with many options. When enabled, a search box appears within each facet category, allowing users to quickly find specific values. This is especially useful for facets with many values, for example, cities or product models. Toggle the **Searchable Facet Values** switch to turn this feature on or off. ## Collapsible facets Collapsible facets let users show or hide individual facet categories to reduce visual clutter. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/collapsible-facets.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=ee49e5a8e16c4d3b93db2e469895acc8) Collapsible facet categories When enabled, each facet category displays a chevron icon. Users can click to collapse categories they're not using, creating a cleaner interface. The collapsed state persists during the user's session. Enabling collapsible facets is recommended when you have many facet categories. Users can focus on the filters they're actively using while hiding others. Toggle the **Collapsible** switch to turn collapsible facet categories on or off. ## Inclusive and exclusive filtering Enable advanced filtering with inclusion and exclusion operators. These filters let users include or exclude a facet from their search results and create complex filter combinations such as "show products from Sony or Samsung, but not refurbished items." When enabled, each facet value displays plus and minus icons: * **+ (Plus)**: Include results that match this facet value. * **- (Minus)**: Exclude results that match this facet value. Use inclusive and exclusive filtering for complex filtering through many facets. For simpler interfaces, turn this setting off to avoid overwhelming users with additional controls. Toggle the **Inclusive/Exclusive** switch to turn this setting on or off. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/inclusive-exclusive-facets.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=2ef343f4a482c001a0ce6665b4742df1) Inclusive and exclusive filtering mode ## Selected facet pills Use facet pills to display selected filters as removable pills before the facet categories. These facet pills provide a visual indicator to users about the facets they're actively filtering by. Users can select individual facet pills to remove that filter from their current search results. A **Clear All** link also appears, letting users remove all active filters at once. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/selected-facet-pills.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=c6410a4246cd1c9f6696d60e4f217409) Selected facet pills display Toggle the **Selected Facet Pills** switch to turn this feature on or off. ## Configuration properties **Datastore** `dropdown` *required* Data source that provides facet categories and values. Must be configured in your UI Studio application. **Facets Title** `string` Optional text label displayed as the heading above the facets panel. **Facets** `array` Configure individual facet fields to display in the component. **Properties** **Field Name** `string` The field name from your datastore to use as a facet. **Display Name** `string` The label shown to users for this facet category (for example, "Manufacturer", "Color"). **Multi Select** `boolean` (default: false) When enabled, allows users to select multiple values within this facet category. **Searchable Facet Values** `boolean` (default: false) When enabled, adds a search box within each facet category for filtering values. This setting is recommended for facets with ten or more values. **Collapsible** `boolean` (default: false) When enabled, facet categories can be collapsed and expanded with chevron icons. The collapsed state persists in the user's session. **Inclusive/Exclusive** `boolean` (default: false) When enabled, displays **+** and **-** icons next to facet values for inclusive or exclusive filtering. This allows complex filter combinations like "include Sony or Samsung, but exclude refurbished". **Selected Facet Pills** `boolean` (default: false) When enabled, displays active filters as removable pills at the top with a **Clear All** option. Shows inclusive (+) or exclusive (-) indicators when Inclusive/Exclusive mode is enabled. **Facets Title Font** `group` Typography settings for the main facets heading or title. **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for facets title. **Font Weight** `dropdown` (default: Regular) Font weight for facets title. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 14) Font size in pixels for facets title. **Facet Field Font** `group` Typography settings for facet category titles (for example, "Manufacturer", "Color"). **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for facet category titles. **Font Weight** `dropdown` (default: Bold) Font weight for facet category titles. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 14) Font size in pixels for facet category titles. **Facet Value Font** `group` Typography settings for facet values (for example, "Sony", "Purple"). **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for facet values. **Font Weight** `dropdown` (default: Regular) Font weight for facet values. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 14) Font size in pixels for facet values. **Search Input** `group` Typography settings for the search input field within facet categories. Used when **Searchable Facet Values** is enabled. **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for search input text. **Font Weight** `dropdown` (default: Regular) Font weight for search input text. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 14) Font size in pixels for search input text. **Selected Filters Header** `group` Typography settings for the "Selected Filters:" header text when Selected Facet Pills is enabled. **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for selected filters header. **Font Weight** `dropdown` (default: Regular) Font weight for selected filters header. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 12) Font size in pixels for selected filters header. **Selected Filter Pill** `group` Typography settings for the filter pill text when Selected Facet Pills is enabled. **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for filter pill text. **Font Weight** `dropdown` (default: Regular) Font weight for filter pill text. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 14) Font size in pixels for filter pill text. **Colors** `group` Color scheme for the facets component. **Properties** **Background** `color` (default: #ffffff) Background color for the facets container. **default** `#ffffff` **Facets Title** `group` Color properties for the facets title. **Properties** **Facets Title Font** `color` (default: #2C3136) Text color for the main facets title. **default** `#2C3136` **Facets Title Background** `color` (default: #ffffff) Background color for the facets title area. **default** `#ffffff` **Facets Title Border** `color` (default: #ffffff) Border color for the facets title area. **default** `#ffffff` **Facet Field** `group` Color properties for the facet field. **Properties** **Facet Field Font** `color` (default: #2C3136) Text color for facet category titles. Ensure sufficient contrast with background. **default** `#2C3136` **Facet Field Background** `color` (default: #ffffff) Background color for facet category title rows. **default** `#ffffff` **Facet Field Border** `color` (default: #ffffff) Border color for facet category title rows. **default** `#ffffff` **Facet Value** `group` Color properties for the facet value. **Properties** **Facet Value Font** `color` (default: #2C3136) Text color for facet values. Ensure sufficient contrast with background. **default** `#2C3136` **Hover Over** `color` (default: #F9FAFB) Background color when hovering over facet values. **default** `#F9FAFB` **Facet Search** `group` Color properties for the facet search input. **Properties** **Facet Search Text** `color` (default: #2C3136) Text color for the search input field within facet categories. **default** `#2C3136` **Facet Search Background** `color` (default: #ffffff) Background color for the search input field within facet categories. **default** `#ffffff` **Selected Filters Header** `group` Color properties for the selected filters header. **Properties** **Title** `color` (default: #2C3136) Text color for the "Selected Filters:" header label. **default** `#2C3136` **Clear All** `color` (default: #0066cc) Text color for the "Clear All" link. **default** `#0066cc` **Selected Filter Pill** `group` Color properties for the selected filter pill. **Properties** **Pill Font** `color` (default: #2C3136) Text color for filter pill labels. **default** `#2C3136` **Pill Background** `color` (default: #E8E8E8) Background color for filter pills. **default** `#E8E8E8` **Pill Border** `color` (default: #d0d0d0) Border color for filter pills. **default** `#d0d0d0` **Pill Icon** `color` (default: #2C3136) Color for the remove icon (×) on filter pills. **default** `#2C3136` **Inclusive/Exclusive Buttons** `group` Color properties for the inclusive/exclusive buttons. **Properties** **Background** `color` (default: #ffffff) Background color for the + and - buttons when Inclusive/Exclusive mode is enabled. **default** `#ffffff` **Border** `color` (default: #ECEEF0) Border color for the + and - buttons when Inclusive/Exclusive mode is enabled. **default** `#ECEEF0` **Active Background** `color` (default: #2C3136) Background color for active + or - buttons when Inclusive/Exclusive mode is enabled. **default** `#2C3136` **Active Icon** `color` (default: #ffffff) Icon color for active + or - buttons when Inclusive/Exclusive mode is enabled. **default** `#ffffff` # Image Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/components/image Display images with optional links and views in UI Studio applications The Image component displays static or dynamic images in your UI Studio pages. Use images to add visual content, branding, product photos, or clickable banners. The component supports clickthrough links, alternative text, and fallback images. ## Basic usage Add an image component to your UI Studio page to display visual content. ![Basic Image component](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/ui-studio-image-button.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=7d2ed2a6cb977a7b2ba2ff29cd978c02) Basic Image component Provide an image URL to display it on your page. The component supports common image formats including JPG, PNG, GIF, and SVG. If the primary image fails, the component automatically loads the fallback image if one is configured. If both images fail, the component does not display in order to avoid broken image icons. If there is no image URL, the component does not render. ## Best practices * Optimize images to reduce file size without sacrificing quality. While Lucidworks does not make a specific recommendation, tools such as TinyPNG, ImageOptim, or your image editor's "Save for Web" feature are available. The recommended maximum file size is 2MB for web display. * If possible, configure a fallback image that displays if the primary image fails to load. * Use appropriate image formats for different content types: * **JPG**: Photos and complex images * **PNG**: Graphics with transparency or text * **SVG**: Logos and icons to ensure correct scaling * **WebP**: Modern format with better compression, if browser support allows * Always provide meaningful Alt (alternative) text that conveys the purpose and content of the image. Screen readers rely on this to describe images to visually impaired users. Alt text also improves SEO and displays when images fail to load. * Avoid using images of text for important content. Screen readers cannot read text embedded in images. ## Configuration properties **Image URL** `string` URL to the image file. **Alt Text** `string` Descriptive text for accessibility and SEO. Describe the image content and purpose. Avoid generic phrases like "image" or "photo". **Link** `string` Clickthrough URL. When configured, clicking the image navigates to this URL. Examples: * `https://www.example.com` * `/products` * `https://example.com/offers` Leave blank for non-clickable images. **Fit Mode** `dropdown` (default: cover) Controls how the image fits within its container dimensions. **Options** **Contain** `option` Scales the image to fit within the container while maintaining aspect ratio. May show letterboxing or pillarboxing (empty space on sides/top/bottom). **Cover** `option` Scales the image to cover the entire container while maintaining aspect ratio. May crop portions of the image. This is the default. **Border Radius (px)** `number` (default: 0) Corner roundness in pixels. * `0` = Square corners (default) * `4-8` = Subtle rounded corners * `12-16` = Noticeably rounded corners * `50+` = Circular (when width equals height) **Fallback Image URL** `string` Optional backup image URL. Displays if the primary image fails to load. # Results Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/components/results Display search results with sorting, pagination, conditional row coloring, and dynamic row linking The Results component displays search results from your datastore in a table format. Use this component to present search findings, product listings, data tables, or any collection of records. The component supports sorting, pagination, conditional row coloring, and dynamic page linking. > **[UI Studio: Crafting the Discovery Experience](https://academy.lucidworks.com/training/019fecaa-3fd4-721e-8985-bf28d235dd76/overview)** > > Learn how to configure the Results List with Grid or Document layouts, set up facets with human-legible field names, and enable search-within-results refinement. ## Basic usage Add a Results component to your UI Studio page to display search results. The component typically works alongside a [Search Bar component](/docs/lw-platform/lw-ui-studio/components/search-bar) and [Facets component](/docs/lw-platform/lw-ui-studio/components/facets) to display and filter query results, but can also work standalone. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/add-results.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=13e18436fe847c170bc2d6ab8ab0cda1) Results component in the canvas When no search query is active, the component displays all records by default. The Results component updates when users apply filters or perform searches. The Results component supports a variety of content types and layouts. Common use cases include: * **Product listings**: A catalog of items for sale, such as an ecommerce store. Create results listings with images, prices, and "Add to Cart" buttons. * **Search results**: A display of documents or records matching a user query. Create results listings with titles, descriptions, and snippets. * **Data tables**: A structured view for tabular data users need to compare or filter. Create results listings with sorting and conditional coloring for status. * **User directory**: A browsable list of users or contacts with role information. Create results listings with profile links and role-based coloring. * **Document library**: A collection of files organized for browsing and download. Create results listings with file types, dates, and download links. ## Display your results The table view displays results as a structured data table with columns and rows. This layout is best for structured data and sortable datasets, as the table view is optimized for dense information display. Click the **+** next to **Columns** to display a column in the results. Columns display in the order that they are added. To keep column headers visible while you scroll through results, turn on the **Sticky Header** toggle. ## Sort options Configure the sort criteria for users. Use these options so that users can sort the results by preset criteria, such as price, name, or quantity. The sort options display in a dropdown menu above the search results. Sorting by relevance is included by default. > [!NOTE] > > The sort options display in the order that you added them. The default Relevance option always appears first in the user-facing dropdown, even though it is listed last in the configuration panel. ## Pagination Use pagination to configure the number of results per page and how many results the user can choose to display per page. When pagination is turned off, only the first page of results displays. When you enable pagination, you can set the default number of results to display per page in the **Default Results Count** field. The default value is 10 results. You can also configure the number of results to display per page for users to select. Set these values in the **Results Count** fields, listed from lowest to highest. ## Conditional row coloring Use conditional row coloring to apply background and text color to rows based on field values, making it easy to surface important information at a glance. Use this feature to flag inventory items with low stock, highlight tasks that are past due, distinguish active records from inactive ones, or draw attention to high-priority items without requiring users to sort or filter the table themselves. Each rule evaluates a field against a condition and a value, then applies the configured colors to any matching row. When you configure multiple rules, the component evaluates them in the order listed and applies the first matching rule. Rows that match no rule use the default table styling. > [!TIP] > > Because the component evaluates rules top to bottom and applies the first match, you can order rules from most critical to least critical status to ensure proper highlighting. **Inventory alerts** An ecommerce catalog uses a `stock_status` field to alert buyers and staff about inventory availability. The rule checks whether `stock_status` equals `Out of stock` and applies a red background to signal that the item is unavailable. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/conditional-row-formatting-availability.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=693f15624cc1c3aa5c4a7968eda517ef) Conditional row formatting based on availability That same approach extends to any number of statuses. A second rule can check whether `stock_status` equals `Low stock` and apply a yellow background to indicate limited availability, and a third can check whether `stock_status` equals `In Stock` and apply a green background to indicate healthy inventory levels. You can continue adding rules for any status value your catalog defines. **In stock** `#f0fdf4` **Limited** `#fefce8` **Out of stock** `#fef2f2` **Status highlighting** A task management table uses a `status` field to communicate record state at a glance. One rule checks whether `status` equals `Active` and applies a green background. Another checks whether `status` equals `Inactive` and applies a gray background. A third checks whether `status` equals `Error` and applies a red background with white text. Use subtle background tints rather than saturated colors so that text remains readable across all rows. **Priority indicators** A support queue uses a `priority` field to help agents triage incoming requests. One rule checks whether `priority` equals `High` and applies red text. Another checks whether `priority` equals `Medium` and applies orange text. A third checks whether `priority` equals `Low` and applies green text. Text color changes alone work well when you want to signal priority without overwhelming the table with heavy background coloring. ## Dynamic page link Use dynamic page links to navigate users directly from a table row to a detail page, connecting your results table to the rest of your application. Use this feature to build product catalog tables where rows link to product detail pages, user directories where names link to profile pages, or document lists where entries open document viewers. When **Link Mode** is set to **Action**, the **Display Type** setting controls how the link appears in the table. Choose **Link** when the field value is a natural, recognizable label that users expect to click, such as a username or a document title. Choose **Button** when the field value is an internal ID or technical string you do not want to display, and the action should appear as a labeled button. To use a redirect button, define the destination URL with the **Page** base path and a **URL Template** that combines the page path with a placeholder for the field value. Wrap the placeholder in curly braces to mark where the field value is injected. The template `/products/PRODUCT_ID` resolves to `/products/ABC123` when the `PRODUCT_ID` field contains `ABC123`. You can position the placeholder anywhere in the template path, such as `/users/{username}/profile` or `/documents/{doc_id}`. You can configure multiple dynamic links on the same table, assigning one link configuration per column. This lets you create multi-action rows with a mix of link types, such as a "View" redirect button in one column alongside an "Edit" button in another. **Product detail link** A product catalog table links each row to its corresponding product detail page. Set **Column** to `PRODUCT_ID`, **Link Mode** to **Action**, **Display Type** to **Button**, **Button Label** to "View Product". Set the **URL Template** to `/products/PRODUCT_ID`. A row where `PRODUCT_ID` contains `ABC123` navigates the user to `/products/ABC123`. **User profile link** A user directory makes the username itself a clickable link to the user profile page. Set **Column** to `username`, **Link Mode** to **Inline**, and **URL Template** to `/users/{username}/profile`. The displayed username becomes a link without a separate button. **Document with action button** A document library hides the internal document ID and exposes only a labeled action button. Set **Column** to `doc_id`, **Link Mode** to **Action**, **Display Type** to **Button**, **Button Label** to "Open Document", and **URL Template** to `/documents/{doc_id}/view`. The document ID is not shown to users. Only the button is displayed. > [!NOTE] > > When creating URL templates for Dynamic Page Links, test with sample data to ensure links resolve correctly. Invalid templates result in broken navigation. ## Configuration properties ### Basic configuration **Datastore** `dropdown` *required* Data source for results. Must be configured in your UI Studio application. **Search Highlighting** `boolean` (default: false) When enabled, highlights search terms within table cells to show matches visually. **Row Striping** `boolean` (default: false) When enabled, alternates row background colors for improved readability. **Columns** `group` Configure which data fields display as table columns. Add multiple columns using the **+** button. **Properties** **Field Name** `string` Field name from your datastore to display as a column. **Display Name** `string` Label shown in the column header. **Display Type** `dropdown` (default: text) How the field content is rendered. **Options** **text** `option` Plain text display. **image** `option` Image display. **date** `option` Formatted date display. **price** `option` Currency-formatted display. **hyperlink** `option` Clickable link display. **Sticky Header** `boolean` (default: true) When enabled, column headers remain visible while scrolling through table rows. **Column Header Font** `group` Typography settings for column headers. **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for column header text. **Font Weight** `dropdown` (default: Bold) Font weight for column header text. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 14) Font size in pixels for column header text. **Sort** `group` Configure available sort criteria for users. The **Relevance** option is included by default and displays last in the sort dropdown. **Properties** **Sort Options** `array` Available sort options. Add multiple options using the + button. **Sort Option Properties** **Field Name** `string` Data field to sort by. **Order** `dropdown` (default: Ascending) Sort direction for this option. **Options** **Ascending** `option` Sort from lowest to highest: A-Z, 0-9, oldest to newest. **Descending** `option` Sort from highest to lowest: Z-A, 9-0, newest to oldest. **Display Name** `string` Label shown to users in the sort dropdown. Examples: "Price: Low to High", "Newest First", "Product Name: A-Z" **Pagination** `group` Configure pagination controls for navigating through result pages. **Properties** **Pagination Enabled** `boolean` (default: true) When enabled, displays pagination controls for navigating through result pages. Otherwise, only the first page of results displays. **Default Results Count** `number` (default: 10) Number of results displayed per page by default. **Results Count** `array` (default: \[10, 20, 50, 100]) Number of results to display per page. **Count Properties** **Count** `number` Number of results per page. Add or remove values using the **+** and **-** buttons to customize available page sizes. **Table Styling & Layout** `group` Visual appearance settings for the table. **Properties** **Cell Value Font** `group` Typography settings for table cell content. **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for cell value text. **Font Weight** `dropdown` (default: Regular) Font weight for cell value text. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 14) Font size in pixels for cell value text. **Text Alignment** `radio` (default: Left) Horizontal alignment for table cell content. **Options** **Left** `option` Align text to the left edge of the column. **Center** `option` Align text to the center of the column. **Right** `option` Align text to the right edge of the column. **Colors** `group` Color scheme for the table. **Properties** **Table Background** `color` (default: #FFFFFF) Background color for the entire table. **default** `#FFFFFF` ### Advanced configuration **Conditional Row Coloring** `group` Apply styling to rows based on field values. **Properties** **If** `dropdown` Column or field to evaluate. **Condition** `dropdown` Comparison operator. **Options** **Equals** `option` Matches rows where the field equals the specified value. **Not equals** `option` Matches rows where the field does not equal the specified value. **Contains** `option` Matches rows where the field contains the specified value. **Not contains** `option` Matches rows where the field does not contain the specified value. **Starts with** `option` Matches rows where the field value begins with the specified text. **Ends with** `option` Matches rows where the field value ends with the specified text. **Value** `string` Value to compare against. The type depends on field and condition. **Background Color** `color` Row background color when condition is true. **Text Color** `color` Row text color when condition is true. Ensure sufficient contrast with background. **Dynamic Page Link** `group` Clickable links or buttons in table columns that navigate to detail pages. **Properties** **Column** `dropdown` Field that provides the link data or navigation context. **Link Mode** `dropdown` (default: Inline) Determines how the link is integrated into the table. **Options** **Inline** `option` Link embedded directly in the cell value. **Action** `option` Separate action link or button alongside the cell value. **Display Type** `dropdown` (default: Link) How the action appears when Link Mode is set to Action. Appears only when **Link Mode** is set to **Action**. **Options** **Link** `option` Displays as a text link. **Button** `option` Displays as a button. **Link Text** `string` Text displayed for the link. Appears only when the **Display Type** is **Link** or when **Link Mode** is **Inline**. **Button Label** `string` Text displayed on the button. Only shown when **Link Mode** is **Action** and **Display Type** is **Button**. **URL Template** `string` URL pattern with placeholders for dynamic values. Format: Use curly braces `{field_name}` as placeholders for field values. Examples: * `/details/PRODUCT_ID` * `/users/{username}/profile` * `/documents/{doc_id}` **Value is URL** `boolean` (default: false) When enabled, treats the column value itself as a complete URL rather than injecting it into the URL Template. **Open in New Tab** `boolean` (default: false) When enabled, opens the link in a new browser tab instead of navigating in the current tab. # Search Bar Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/components/search-bar Interactive search input with typeahead autocomplete suggestions in UI Studio applications The Search Bar component in UI Studio provides a text input field for users to search for content. Use search bars to enable keyword searching with optional typeahead autocomplete that suggests results as users type. The component supports customizable placeholder text, styling, and configurable typeahead suggestions. Pair the search bar component with the [results component](/docs/lw-platform/lw-ui-studio/components/results) and the [facets component](/docs/lw-platform/lw-ui-studio/components/facets) to build a complete search experience. > **[UI Studio: Building the Search Entry Point](https://academy.lucidworks.com/training/019fd941-8756-78d5-a40e-7d39048b4572/overview)** > > Learn how to configure the Search Bar component with Typeahead, map it to a Fusion query profile, and customize its placeholder text and styling. ## Basic usage Add a search bar component to your UI Studio page to enable search capability. To build a minimal search component, you must set values for the Name and Datastore fields. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/add-search.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=fc5a1d5e154f2f733cabaa59c424e038) Search Bar component dropped into the header section Users type queries and press Enter to search. > **[UI Studio: Data Integration & Customization](https://academy.lucidworks.com/training/019fd952-23b7-7190-8343-71c7d3ea6850/overview)** > > Learn how to link UI Studio components to Fusion datastores for live data, then use preview mode to validate the experience. ## Typeahead You can enable autocomplete suggestions that appear as users type. When typeahead is enabled, the search bar displays a dropdown of suggested queries as users type. Users can: * Click a suggestion to search for it. * Use arrow keys to navigate suggestions. * Press Enter to search the highlighted suggestion. * Press Escape to close the dropdown. To configure typeahead, you must have a configured typeahead datasource. This datasource can be the same as your primary datasource for search. If the endpoint is missing or unreachable, UI Studio automatically deactivates typeahead to prevent errors. > [!NOTE] > > Typeahead suggestions improve discoverability and reduce typos, but they also add complexity. Turn the typeahead setting off for simple search scenarios or when your dataset is small. Expand the **Typeahead** section to configure autocomplete behavior and appearance. ### Suggestion count Set the maximum number of typeahead suggestions to display in the **Suggestion Count** field. Enter a number in the **Suggestion Count** field, for example, 5, 10, or 15. The default value is 10 suggestions. Keep suggestion counts between 5 and 10 to balance performance and suggestion variety. Too few suggestions limit discovery, while too many suggestions can overwhelm users. ### Search character count Set the minimum number of characters required before showing suggestions. Enter a number in the **Search Character Count** field, for example, 2, 3, or 4. Setting a higher number prevents typeahead from triggering on very short queries that would return too many broad suggestions. If you have a dataset with distinct terms, use a lower value. > [!NOTE] > > Higher character counts reduce the number of typeahead API calls, improving performance. However, higher character counts also delay when users see useful suggestions. ## Configuration properties **Name** `string` *required* Component identifier for organization and reference. The name does not display on your user-facing website. **Datastore** `dropdown` *required* Primary data source for search queries. Must be configured in your UI Studio application. **Typeahead Datastore** `dropdown` Data source for autocomplete suggestions. This datastore can be the same as the main datastore or a separate optimized source. If the endpoint is missing or unreachable, typeahead is automatically deactivated to prevent errors. **Placeholder Text** `string` (default: Search anything...) Hint text displayed when the search bar is empty. Should be concise and descriptive. **Placeholder Text Style** `group` Typography settings for placeholder text. **Properties** **Font Family** `dropdown` (default: Public Sans) Font family for placeholder text. **Font Weight** `dropdown` (default: Regular) Font weight for placeholder text. **Options** **Regular** `option` Standard weight. **Bold** `option` Heavy weight. **Font Size** `number` (default: 14) Font size in pixels for placeholder text. **Colors** `group` Color scheme for the search bar. **Properties** **Search Bar** `color` (default: #F5F8FA) Background color for the search input field. **default** `#F5F8FA` **Placeholder Text** `color` (default: #999999) Text color for placeholder text. Should be lighter than entered text for clear distinction. **default** `#999999` **Typeahead** `group` Autocomplete suggestion settings. **Properties** **Enabled** `boolean` (default: true) When enabled, displays autocomplete suggestions as users type. Typeahead is enabled by default but requires a configured Typeahead datastore. This datastore can be the same as your search datastore. If no datastore is configured, typeahead is automatically deactivated. **Suggestion Count** `number` (default: 10) Maximum number of autocomplete suggestions to display. Recommended range: 5 to 10 **Search Character Count** `number` (default: 3) Minimum number of characters required before showing typeahead suggestions. Recommended range: 2 to 5 **Dropdown Background** `color` (default: #ffffff) Background color for the suggestions dropdown. **default** `#ffffff` **Item Hover Background** `color` (default: #F5F8FA) Background color when hovering over a suggestion. **default** `#F5F8FA` **Item Selected Background** `color` (default: #F5F8FA) Background color for keyboard-selected suggestions. **default** `#F5F8FA` **Item Active Background** `color` (default: #F5F5F5) Background color for actively selected items. **default** `#F5F5F5` **Item Text Color** `color` (default: #2C3136) Text color for suggestion items. **default** `#2C3136` **Font Family** `dropdown` (default: Public Sans) Font family for typeahead suggestion text. **Font Weight** `dropdown` (default: Regular) Font weight for typeahead suggestion text. **Font Size** `number` (default: 14) Font size in pixels for typeahead suggestion text. # Text Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/components/text Display and format text content with rich styling options in UI Studio applications The Text component of UI Studio lets you create formatted text that displays on your UI Studio pages. Use text components to add headings, paragraphs, instructions, labels, or any textual content. The text in the component can be configured to display in various formats such as italic, underline, specific text alignment, and custom styling. ## Basic usage Add a text component to your UI Studio page to display content. ![Basic Text component](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/ui-studio-text-example.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=e90a3b4fc700697c7aea0dcef55cc50e) Basic Text component Enter your text content and apply formatting to create visually appealing, readable content. ## Best practices * Format similar items consistently. For example, if you bold important terms in one text component, use the same format for all important terms. * Limit the number of fonts and font sizes on a specific UI Studio page. Use a font type that reflects your organization's design. For font size, select one for all headings, another for body text, and another for footnotes and other small text. * Avoid using multiple emphasis styles on the same text. For example, choose just bold, but do not underline or italicize the same text as well. ## Configuration properties ### Basic properties **Text** `string` The text content to display. Supports rich text formatting when Font options are applied. Text line length is 50-75 characters for optimal readability, but use 35-50 characters for mobile devices. **Font** `group` Typography settings for the text. **Properties** **Family** `dropdown` (default: Public Sans) Font typeface for the text. **Weight** `dropdown` (default: Regular) Font weight for the text. Options are Regular, Light, Bold, and Extra Bold. **Size** `number` (default: 14) Font size in pixels. Recommended ranges: * Body text: 14-16px. * Headings: 18-32px. * Small text: 12-13px. **Italic** `boolean` When enabled, the text is italicized. **Underline** `boolean` When enabled, the text is underlined. **Text Alignment** `option` How the text is aligned in the text field. Options are Left, Center, or Right. **Colors** `group` Color settings for the text. **Properties** **Font Color** `color` (default: #2C3136) Text color for the component. **default** `#2C3136` ### Advanced properties **Padding Top** `integer` The amount of whitespace at the top of the text field in pixels. **Padding Left** `integer` The amount of whitespace on the left edge of the text field in pixels. # Compositions Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/compositions A composition is the top-level container you build, version, and publish in UI Studio. A composition contains one or more pages, each with its own URL. You arrange components on each page's canvas, configure them, and publish when ready. UI Studio tracks every save as a new version so you can view the full history of your work. > **[UI Studio: Navigating the Workspace](https://academy.lucidworks.com/training/019fd953-64f2-7595-a328-2bb17e404165/overview)** > > Learn how to access the UI Studio home page and manage your existing compositions. ## The compositions list The Compositions screen shows all compositions in your environment. Each row displays the composition name and the date and time it was last edited. Click any row to open the composition in the editor. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/compositions-main.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=f4dbb51ff11910f83cf8169f295b59b1) The Compositions screen, where you create, manage, and publish your UI Studio compositions. Use the search bar to filter compositions by name or description. Use the **Filters** button to filter by a date range for the Last Edited On column. Click the **Name** or **Last Edited On** column headers to sort the list. > **Add a composition** > > Follow these steps to add a new composition. > > **1. Open the Compositions screen** > > Navigate to **UI Studio** in the left navigation panel and click **Builder**. > > **2. Click Create New UI** > > On the Compositions screen, click **Create New UI**, enter a name and description for the composition, and click **Create**. > > ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-add-new.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=edd06b9be4a134296698bee6a2873697) > > Add a new composition. > > The new composition is listed on the Compositions screen. You can now select the composition and build it. > **Build a composition** > > Follow these steps to add components to build a composition. > > **1. Open the Compositions screen** > > Navigate to **UI Studio** in the left navigation. > > **2. Select a composition** > > Select a composition from the list. > > **3. Start building** > > The new composition opens in the editor. > > **Composition** > > **Search Page** > > **Search Bar** > > **Results** > > **Facets** > > **Details Page** > > **Text** > > **Image** > > **Button** > > * Add pages, and then click the main canvas. Click the gear icon of the canvas to open the **Customize Section** panel and set the canvas color and size. > > * Drag components from the left panel onto the canvas to build your page layout. > > * Click any component to select it and configure it in the **Customize** panel. > > * Repeat across pages until your composition is ready, then save your work. > > The Quickstart walks through this process end to end, and the component documentation covers every configuration option. > > > **[Quickstart](/docs/lw-platform/lw-ui-studio/quickstart)** > > > > Get up and running with your first UI Studio page in minutes. > > > **[Components](/docs/lw-platform/lw-ui-studio/components/search-bar)** > > > > Browse available components and learn how to configure them. > **Manage pages in a composition** > > A composition contains one or more pages. Each page has a name and a URL path. One page is designated as the home page, which loads when a user visits the root of your published composition. Pages can also contain subpages, each with a URL path nested under the parent page's path. > > ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/composition-pages.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=cff44ab14fc94ef0179f48d46dcd2dcd) > > Page management in a composition. > > **Name** `string` *required* > > Display name for the page. > > **URL** `string` *required* > > URL path for the page, relative to the composition's root URL. > > **Home Page** `boolean` > > When true, this page loads when a user visits the root of the published composition. Only one page can be the home page. > > **Subpages** `array` > > Optional child pages nested under this page's URL path. Each subpage has the same configuration options as a top-level page. > **Publish a composition** > > Publishing makes your composition available at a public URL in the format `YOUR_COMPANY.ui.lucidworks.cloud/COMPOSITION_NAME`. > > **1. Click Publish** > > In the composition's editor screen, click **Publish**. > > **2. Confirm publication details** > > Review and confirm the location to publish. It typically includes your company name, composition name, and page title. Click **Publish**. > > ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-publish.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=934e711013349a02a87f3d89aaffe0ae) > > Add a new composition. > > > [!NOTE] > > > > The published URL uses the composition name. To change the URL, update the composition name before publishing. ## End-user single sign-on for published compositions UI Studio supports end-user Single Sign-On (SSO) using Okta OIDC and controls access for end users who visit published search sites. When enabled, users must authenticate before accessing a published composition at `YOUR_COMPANY.ui.lucidworks.cloud/COMPOSITION_NAME`. When SSO is not enabled, the published URL is publicly accessible. To enable UI Studio SSO for your published compositions, contact your Lucidworks representative. > [!NOTE] > > UI Studio SSO is different from Lucidworks Platform SSO, which controls access for administrators who build and manage compositions in the Lucidworks Platform workspace. ## Composition settings Settings apply at the composition level and affect all pages. Access settings from the editor toolbar. ### Branding Upload a logo and favicon for your composition. These appear in the browser tab and any branded areas of your pages. **Logo** `file` Image file displayed in branded areas of your composition. **Favicon** `file` Icon file displayed in the browser tab. ### Localization Configure the language, timezone, and date and time format for your composition. These settings affect how dates and times display across all pages. **Language** `string` Language code for the composition, for example, `en-US`. **Timezone** `string` Timezone for the composition, for example, `America/Los_Angeles`. **Date and time format** `string` Format string for displaying dates and times, for example, `MM/DD/YYYY h:mm A`. ### Authentication Configure single sign-on (SSO) for your composition using OIDC. **Enabled** `boolean` When true, SSO is required to access the composition. **Session duration** `number` How long, in hours, a user session remains valid. **Session extension threshold** `number` How many minutes before session expiry a session is eligible for extension. **OIDC** `group` Identity provider configuration for the OIDC protocol. **OIDC settings** **Client ID** `string` *required* Client identifier registered with your identity provider. **Client secret** `string` *required* Client secret registered with your identity provider. **Issuer URI** `string` *required* Base URI of your identity provider. **Authorization URI** `string` *required* URI where users are redirected to authenticate. **Token URI** `string` *required* URI used to exchange authorization codes for tokens. **JWKS URI** `string` *required* URI of your identity provider's JSON Web Key Set. **Userinfo URI** `string` URI used to retrieve user profile information. **End session endpoint** `string` URI used to log users out of the identity provider. **Scopes** `string[]` OAuth scopes to request from the identity provider, for example, `openid`, `profile`, `email`. # UI Studio Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/overview Build interactive search experience pages with drag-and-drop canvas sections, pre-built components, and no-code configuration. UI Studio lets you create and publish search experience pages without writing code. Arrange pre-built components on visual canvas sections, connect them to your datastore, and deploy directly to your users. **UI Studio compositions** ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/compositions-main.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=f4dbb51ff11910f83cf8169f295b59b1) The Compositions screen, where you create, manage, and publish your UI Studio compositions. **UI Studio drag-and-drop** ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/compositions-drag-and-drop.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=85ce313569760f8be0725e14640bb7b4) Drag components from the left panel onto canvas sections to arrange your page layout. **UI Studio editor** ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/add-facets.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=99c08be5a277270ba2b2e55f5c11ff02) The UI Studio editor, with the component palette on the left and the Customize panel on the right. ## How UI Studio works **Compositions are standalone web experiences.** A composition works like a self-contained website, made up of one or more pages, each with its own URL. Arrange components on each page's canvas sections, configure them independently, and publish when ready. **Components reflect your data.** Components retrieve and display data from a configured datastore. Your datastore changes update automatically. **Configuration is visual.** Use the Customize panel to adjust component settings, styling, and behavior without editing code. **Your changes are backed up automatically.** UI Studio saves your composition history as you work. If you need to revert a critical change, contact your Lucidworks representative. **Publishing generates a public URL.** When you publish, your composition is hosted and immediately available to your users. ## Get started > **[Quickstart](/docs/lw-platform/lw-ui-studio/quickstart)** > > Get up and running with your first UI Studio page in minutes. > **[UI Studio: Data Integration & Customization](https://academy.lucidworks.com/training/019fd952-23b7-7190-8343-71c7d3ea6850/overview)** > > Learn how to link UI Studio components to Fusion datastores for live data, then use preview mode to validate the experience. ## Build your app > **[Compositions](/docs/lw-platform/lw-ui-studio/compositions)** > > Arrange and manage page layouts using composition canvas sections. ## Components Use pre-built components to build interactive search experiences. > **[Search Bar](/docs/lw-platform/lw-ui-studio/components/search-bar)** > > Accept user queries and trigger search across your datastore. > **[Results](/docs/lw-platform/lw-ui-studio/components/results)** > > Display search results views with sorting and pagination. > **[Facets](/docs/lw-platform/lw-ui-studio/components/facets)** > > Let users narrow results by filtering on field values. > **[Button](/docs/lw-platform/lw-ui-studio/components/button)** > > Add navigation, export, or action buttons to your pages. > **[Image](/docs/lw-platform/lw-ui-studio/components/image)** > > Display images with optional links, borders, and fallback support. > **[Text](/docs/lw-platform/lw-ui-studio/components/text)** > > Add static or dynamic text content with rich styling options. # Quickstart Source: https://doc.lucidworks.com/docs/lw-platform/lw-ui-studio/quickstart Build a basic search interface in UI Studio Builder with Search Bar, Results, and Facets components. This guide walks you through building a basic but functional search interface in UI Studio Builder. By the end, you will have a composition with a Search Bar, Results, Facets, Text, Image, and Button component working together as a complete search experience. > [!NOTE] > > For more information, see [Compositions](/docs/lw-platform/lw-ui-studio/compositions). **1. Add a composition** Navigate to **UI Studio** in the left navigation panel and click **Builder**. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/compositions-main.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=f4dbb51ff11910f83cf8169f295b59b1) The Compositions screen, where you create, manage, and publish your UI Studio compositions. On the Compositions screen, click **Create New UI**. Enter a name and description for the composition and click **Create**. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-add-new.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=edd06b9be4a134296698bee6a2873697) Add a new composition. The new composition is listed on the Compositions screen. You can now select the composition and build it. **2. Open your composition** On the Compositions screen, click a composition to open it in the editor. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-new-editor.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=b278cd085415046cc47371f1b3cb532d) Composition Editor screen **3. Set canvas properties** Click the main canvas and then click the gear icon to open the **Customize** panel on the right. Set a background color to match your company's branding, or adjust the section dimensions. These settings can be refined at any time. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-canvas-properties.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=aeebfe42c44115426cbc5a184e88c181) Customize canvas properties **4. Add components** In the left panel of the Editor screen, click **Components**. Available components are listed in the left sidebar, organized into two categories: **Search** and **Content**. ![](https://mintcdn.com/lucidworks/ttOgnfuG35q331Yl/assets/images/lw-platform/ui-studio/composition-components.png?fit=max\&auto=format\&n=ttOgnfuG35q331Yl\&q=85\&s=fae1ef879358dd48411b3a25e677045b) Composition components > [!NOTE] > > To customize each component, click the component in the Editor screen and select values in the **Customize** panel on the right. Set a background color to match your company's branding, or adjust the section dimensions. These settings can be refined at any time. **5. Add a Search Bar** > **[Search Bar](/docs/lw-platform/lw-ui-studio/components/search-bar)** > > Accept user queries and trigger search across your datastore. In the left sidebar, find the **Search Bar** under the **Search** category. Drag it from the sidebar and hover over the header section in the canvas. The interface indicates where the component will land as you hover. Drop it into position. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/add-search.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=fc5a1d5e154f2f733cabaa59c424e038) Search Bar component dropped into the header section The **Customize** panel opens on the right with the Search Bar configuration options. Configure the following: * **Datastore**: Select the datastore you want to use for search queries. * **Typeahead Datastore**: Select the datastore for autocomplete suggestions. This can be the same datastore as the one above. * **Placeholder Text**: Replace the default text with something descriptive for your users, such as `Search our site`. * **Typeahead**: Expand this section and toggle **Typeahead Enabled** to turn autocomplete on or off. > **[UI Studio: Data Integration & Customization](https://academy.lucidworks.com/training/019fd952-23b7-7190-8343-71c7d3ea6850/overview)** > > Learn how to link UI Studio components to Fusion datastores for live data, then use preview mode to validate the experience. For details on all Search Bar settings, see the [Search Bar](/docs/lw-platform/lw-ui-studio/components/search-bar) component documentation. **6. Add a Results component** > **[Results](/docs/lw-platform/lw-ui-studio/components/results)** > > Display search results in a table view with sorting and pagination. Drag the **Results** component from the **Search** category in the left sidebar and drop it into the body area of the canvas. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/add-results.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=13e18436fe847c170bc2d6ab8ab0cda1) Results component in the canvas In the **Customize** panel, set the **Datastore** to the same datastore you selected for the Search Bar. This ensures the Results component displays results from the same search. Adjust the **Pagination** setting from the default to control how many results appear per page. > [!TIP] > > Advanced compositions may use multiple Search Bars and Results components to support separate search experiences on the same page. For example, a company intranet might have one for document search and another for people search. To accommodate this, add a new section to the canvas by hovering between existing sections, where the option to create a new section appears. For details on all Results settings, see the [Results](/docs/lw-platform/lw-ui-studio/components/results) component documentation. **7. Add a Facets component** > **[Facets](/docs/lw-platform/lw-ui-studio/components/facets)** > > Let users narrow results by filtering on field values. Drag the **Facets** component from the **Search** category and drop it onto the canvas alongside the Results. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/add-facets.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=99c08be5a277270ba2b2e55f5c11ff02) Facets component in the canvas In the **Customize** panel, set the **Datastore** to the same datastore as the Search Bar and Results. This ensures the facets filter the same set of results. Configure a few options to shape the filtering experience: * **Searchable Facet Value**: Toggle this on to add a search box within each facet category. This is helpful when a category has many values. * **Collapsible**: Toggle this on to let users collapse and expand individual facet categories to save space. * **Selected Facet Pills**: Toggle this on to show active filters as removable pills at the top of the facets panel. For details on all Facets settings, see the [Facets](/docs/lw-platform/lw-ui-studio/components/facets) component documentation. **8. Add content components** > **[Text](/docs/lw-platform/lw-ui-studio/components/text)** > > Add text content with rich styling options. > **[Image](/docs/lw-platform/lw-ui-studio/components/image)** > > Display images with optional links, borders, and fallback support. > **[Button](/docs/lw-platform/lw-ui-studio/components/button)** > > Add navigation, export, or action buttons to your pages. With the core search components in place, add content components from the **Content** category in the left sidebar: **Text**, **Image**, and **Button**. * **Text**: Drag a Text component onto the canvas. For example, place it above the Results component as a section heading. The canvas layout adapts flexibly as you place components. * **Image**: Drag an Image component next to the Search Bar in the header section. In the **Customize** panel, upload your company logo and set an appropriate width and height. * **Button**: Drag a Button component onto the canvas. In the **Customize** panel, set the **Type** to **Link**, enter a label such as `Visit our site`, and enter your company site URL in the **Page Path** field. Explore the configuration options for each component. For details, see the [Text](/docs/lw-platform/lw-ui-studio/components/text), [Image](/docs/lw-platform/lw-ui-studio/components/image), and [Button](/docs/lw-platform/lw-ui-studio/components/button) component documentation. **9. Save or publish your composition** When you are satisfied with your composition, use the toolbar at the top of the builder to save or publish it. ![](https://mintcdn.com/lucidworks/qwknCXYlTmFH7Hq2/assets/images/lw-platform/ui-studio/publish-composition.png?fit=max\&auto=format\&n=qwknCXYlTmFH7Hq2\&q=85\&s=7f877a345364cabd8a99003193195dd3) Publish confirmation screen After publishing, preview the composition to see the user experience. Test a search query, apply facet filters, and confirm that the results update as expected. # Create bulk operation Source: https://doc.lucidworks.com/api-reference/bulk-operations/create-bulk-operation /api-reference/saas/cs-rules-rewrites.json post /bulk-operations Create a new bulk operation to perform actions on multiple rules. Supports publish, unpublish, edit, delete, and migrate operation types. Operations execute asynchronously. # Delete bulk operation Source: https://doc.lucidworks.com/api-reference/bulk-operations/delete-bulk-operation /api-reference/saas/cs-rules-rewrites.json delete /bulk-operations/{id} Delete a bulk operation record. This removes the operation from the system but does not reverse changes already applied to rules. # Get bulk operation Source: https://doc.lucidworks.com/api-reference/bulk-operations/get-bulk-operation /api-reference/saas/cs-rules-rewrites.json get /bulk-operations/{id} Retrieve details of a specific bulk operation including current status, individual rule statuses, and error messages for failed rules. # List bulk operations Source: https://doc.lucidworks.com/api-reference/bulk-operations/list-bulk-operations /api-reference/saas/cs-rules-rewrites.json get /bulk-operations List all bulk operations with optional filtering and pagination. Returns operations of all types including publish, unpublish, edit, delete, and migrate. # Update bulk operation Source: https://doc.lucidworks.com/api-reference/bulk-operations/update-bulk-operation /api-reference/saas/cs-rules-rewrites.json put /bulk-operations/{id} Update an existing bulk operation. Used to modify operation parameters or retry failed rules. # FAQ Enrichment use case Source: https://doc.lucidworks.com/api-reference/create-predictions/faq-enrichment-use-case /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/faq-enrichment/{MODEL_ID} The FAQ enrichment use case uses a large language model (LLM) to ingest input text and return a JSON response that contains a list of question and answer pairs. # Image metadata enrichment use case Source: https://doc.lucidworks.com/api-reference/create-predictions/image-metadata-enrichment-use-case /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/image-metadata-enrichment/{MODEL_ID} In the image metadata enrichment use case, the LLM ingests a text containing either a base64-encoded image or a public HTTP/HTTPS or Google Cloud Storage (`gs://`) image link and routes the image to a multimodal model. A JSON response is returned that contains an `imageMetadata` dictionary with a list of keywords, subcategories, and keyword synonyms. The POST request obtains and indexes prediction information related to the specified use case, and returns a unique `predictionId` and `status` of the request. The `predictionId` can be used later in the GET request to retrieve the results. # Keyword extraction use case Source: https://doc.lucidworks.com/api-reference/create-predictions/keyword-extraction-use-case /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/keyword-extraction/{MODEL_ID} In the keyword-extraction use case, the LLM ingests text and returns a JSON response that contains a list of keywords extracted from the text. No options can be configured. The POST request obtains and indexes prediction information related to the specified use case, and returns a unique `predictionId` and `status` of the request. The `predictionId` can be used later in the GET request to retrieve the results. # Model predictions by use case Source: https://doc.lucidworks.com/api-reference/create-predictions/model-predictions-by-use-case /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/{USE_CASE}/{MODEL_ID} This is an all-purpose prediction endpoint you can use by specifying a `USE_CASE` and `MODEL_ID`. Upon submission, the API responds with a unique `predictionId` and a `status`. The `predictionId` can be used later in the GET request to retrieve the results. IMPORTANT: The available use cases are detailed in their own section in this specification. # Named Entity Recognition (NER) use case Source: https://doc.lucidworks.com/api-reference/create-predictions/named-entity-recognition-ner-use-case /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/ner/{MODEL_ID} In the Named Entity Recognition (NER) use case, the LLM ingests text and entities to extract and return a JSON response that contains a list of entities extracted from the text. No options can be configured. This use case can be used to extract nouns and proper nouns such as Brand, Date, Company, Places, and Category in order to guide and refine searches. The POST request obtains and indexes prediction information related to the specified use case, and returns a unique `predictionId` and `status` of the request. The `predictionId` can be used later in the GET request to retrieve the results. # Passthrough use case Source: https://doc.lucidworks.com/api-reference/create-predictions/passthrough-use-case /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/passthrough/{MODEL_ID} The passthrough use case lets you use the service as a proxy to the large language model (LLM). The service sends text (no additional prompts or other information) to the LLM. The POST request obtains and indexes prediction information related to the specified use case, and returns a unique `predictionId` and `status` of the request. The `predictionId` can be used later in the GET request to retrieve the results. # RAG use case Source: https://doc.lucidworks.com/api-reference/create-predictions/rag-use-case /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/rag/{MODEL_ID} The rag use case uses candidate documents that are inserted into a LLM’s context to ground the generated response to those documents instead of generating an answer from details stored in the LLM’s trained weights. This type of search adds guardrails so the LLM can search private data collections. The RAG search can perform queries against external documents passed in as part of the request. The POST request obtains and indexes prediction information related to the specified use case, and returns a unique `predictionId` and `status` of the request. The `predictionId` can be used later in the GET request to retrieve the results. # Standalone query rewriter Source: https://doc.lucidworks.com/api-reference/create-predictions/standalone-query-rewriter /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/standalone-query-rewriter/{MODEL_ID} The standalone query rewriter use case rewrites the text in reference to the context based on the memoryUuid. The POST request obtains and indexes prediction information related to the specified use case, and returns a unique `predictionId` and `status` of the request. The `predictionId` can be used later in the GET request to retrieve the results. # Summarization use case Source: https://doc.lucidworks.com/api-reference/create-predictions/summarization-use-case /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/summarization/{MODEL_ID} In the summarization use case, the LLM ingests text and returns a summary of the text as a response. The context length is 2048 tokens. No options can be configured. The POST request obtains and indexes prediction information related to the specified use case, and returns a unique `predictionId` and `status` of the request. The `predictionId` can be used later in the GET request to retrieve the results. # Get prediction results Source: https://doc.lucidworks.com/api-reference/fetch-predictions/get-prediction-results /api-reference/saas/machine-learning-platform-async-prediction.json get /ai/async-prediction/{PREDICTION_ID} Fetch the results of a prediction task by its ID. # Classification use case Source: https://doc.lucidworks.com/api-reference/get-predictions/classification-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/classification/{MODEL_ID} The classification use case lets you use embedding models to compute similarity scores between the incoming text and the labels. It returns the labels ranked in order of most similar to least similar. The classification use case is compatible with all Lucidworks hosted pre-trained and custom embedding models. The default behavior of embedding models is to always have a score returned. The `topK` and `similarityCutoff` parameters can be used to achieve behaviors where only the following are returned: * The single most applicable label * Labels with similarities that exceed a threshold * A set number of items * A set number if it exceeds the threshold # Custom model prediction Source: https://doc.lucidworks.com/api-reference/get-predictions/custom-model-prediction /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/embedding/{MODEL_ID} The custom model prediction is an embedding use case. If a custom model is trained and deployed using the Lucidworks AI Models API, the `DEPLOYMENT_ID` in the Models API is the same value as the `MODEL_ID` you enter in the custom model to return a prediction. # English language model text encoder Source: https://doc.lucidworks.com/api-reference/get-predictions/english-language-model-text-encoder /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/embedding/text-encoder The English language encoder is an embedding use that takes in plain English text and returns a 768-dimensional vector encoding of that text. This model powers this semantic search. The API truncates incoming text to approximately 256 words before the model encodes it and returns a vector. An example usage pattern is to encode all the texts and descriptions in a website and then use this encoder on query text, supporting natural language queries such as "1990s children’s fiction". Each API request includes one batch containing up to 32 text strings. # FAQ Enrichment use case Source: https://doc.lucidworks.com/api-reference/get-predictions/faq-enrichment-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/faq-enrichment/{MODEL_ID} The FAQ enrichment use case uses a large language model (LLM) to ingest input text and return a JSON response that contains a list of question and answer pairs. # Image metadata enrichment use case Source: https://doc.lucidworks.com/api-reference/get-predictions/image-metadata-enrichment-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/image-metadata-enrichment/{MODEL_ID} In the image metadata enrichment use case, the LLM ingests a text containing either a base64-encoded image or a public HTTP/HTTPS or Google Cloud Storage (`gs://`) image link and routes the image to a multimodal model. A JSON response is returned that contains an `imageMetadata` dictionary with a list of keywords, subcategories, and keyword synonyms. The metadata can be generated based on the image, the image title, and the categories. # Keyword extraction use case Source: https://doc.lucidworks.com/api-reference/get-predictions/keyword-extraction-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/keyword-extraction/{MODEL_ID} In the keyword-extraction use case, the LLM ingests text and returns a JSON response that contains a list of keywords extracted from the text. No options can be configured. # Model predictions by use case Source: https://doc.lucidworks.com/api-reference/get-predictions/model-predictions-by-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/{USE_CASE}/{MODEL_ID} This is an all-purpose prediction endpoint you can use by specifying a `USE_CASE` and `MODEL_ID`. IMPORTANT: The available use cases are detailed in their own section in this specification. # Named Entity Recognition (NER) use case Source: https://doc.lucidworks.com/api-reference/get-predictions/named-entity-recognition-ner-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/ner/{MODEL_ID} In the Named Entity Recognition (NER) use case, the LLM ingests text and entities to extract and return a JSON response that contains a list of entities extracted from the text. No options can be configured. This use case can be used to extract nouns and proper nouns such as Brand, Date, Company, Places, and Category in order to guide and refine searches. # Part Number Detection use case Source: https://doc.lucidworks.com/api-reference/get-predictions/part-number-detection-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/part-number-detection/{CUSTOM_DEPLOYMENT_ID} The Part Number Detection use case of the LWAI Prediction API detects part numbers in order to help with query routing and classification, and uses the embedding model to ingest text and return a JSON response of `true` if the input is a part number, or `false` if the input is not a part number. # Passthrough use case Source: https://doc.lucidworks.com/api-reference/get-predictions/passthrough-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/passthrough/{MODEL_ID} The passthrough use case lets you use the service as a proxy to the large language model (LLM). The service sends text (no additional prompts or other information) to the LLM and returns a response. # RAG use case Source: https://doc.lucidworks.com/api-reference/get-predictions/rag-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/rag/{MODEL_ID} The rag use case uses candidate documents that are inserted into a LLM’s context to ground the generated response to those documents instead of generating an answer from details stored in the LLM’s trained weights. This type of search adds guardrails so the LLM can search private data collections. The RAG search can perform queries against external documents passed in as part of the request. # Standalone query rewriter Source: https://doc.lucidworks.com/api-reference/get-predictions/standalone-query-rewriter /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/standalone-query-rewriter/{MODEL_ID} The standalone query rewriter use case rewrites the text in reference to the context based on the memoryUuid. # Summarization use case Source: https://doc.lucidworks.com/api-reference/get-predictions/summarization-use-case /api-reference/saas/machine-learning-platform-predict.json post /ai/prediction/summarization/{MODEL_ID} In the summarization use case, the LLM ingests text and returns a summary of the text as a response. The context length is 2048 tokens. No options can be configured. # Cartadd signals Source: https://doc.lucidworks.com/api-reference/get-signals/cartadd-signals /api-reference/saas/lw-platform-signals.json post /retail/signals/cartadd When a user adds an item to the cart for a potential sale, the information is contained in the cartadd signal. # Click signals Source: https://doc.lucidworks.com/api-reference/get-signals/click-signals /api-reference/saas/lw-platform-signals.json post /retail/signals/click When a user clicks on an item displayed from your site, including results returned from a query, the information is contained in a click signal. # Purchase complete signals Source: https://doc.lucidworks.com/api-reference/get-signals/purchase-complete-signals /api-reference/saas/lw-platform-signals.json post /retail/signals/purchase When a user completes a purchase and is taken to the order confirmation page, a signal is recorded. # Query signals Source: https://doc.lucidworks.com/api-reference/get-signals/query-signals /api-reference/saas/lw-platform-signals.json post /retail/signals/query When a user enters text to search your site, a query request is generated and the information is contained in a query signal. # Tokenization by MODEL_ID Source: https://doc.lucidworks.com/api-reference/get-tokens/tokenization-by-model_id /api-reference/saas/machine-learning-platform-tokenization.json post /ai/tokenization/{MODEL_ID} The tokenization request for the pre-trained and custom embedding use cases and specified embedding `modelId` (model name) sends text to return results in formats supported by embedding models. # Get typeahead suggestions Source: https://doc.lucidworks.com/api-reference/get-typeahead-suggestions /api-reference/saas/lw-platform-typeahead.json get /typeahead/suggestions The `GET /typeahead/suggestions` request retrieves a list of typeahead suggestions. A total of 5,000 suggestions are allowed in the following distribution: 1. Your organization can enter a maximum of 4,000 custom terms (included and excluded) in the Core Settings Typeahead user interface. 2. Every hour, a maximum of 1,000 of the terms entered most often in customer searches are added to the Included typeahead suggestions list. Results are sorted alphabetically. Sort options are not currently available. The optional `prefix` query parameter filters suggestions returned. For example, `GET /typeahead/suggestions?prefix=El` returns the suggestions that begin with the letters `El`. The optional `limit` query parameter limits the maximum number of suggestions returned. For example, `GET /typeahead/suggestions?limit=10` returns a maximum of 10 suggestions. # Passthrough prompt Source: https://doc.lucidworks.com/api-reference/passthrough-prompt/passthrough-prompt /api-reference/saas/machine-learning-platform-prompt-passthrough.json post /ai/prompt/passthrough/{MODEL_ID} The prompt request for the passthrough use case and specified generative AI (GenAI) `modelId` (model name) sends text to return results in formats supported by generative AI (GenAI) models. # Create a query rewrite Source: https://doc.lucidworks.com/api-reference/query-rewrite-management/create-a-query-rewrite /api-reference/saas/cs-rules-rewrites.json post /query-rewrites Create a query rewrite in Commerce Studio. # Delete a query rewrite Source: https://doc.lucidworks.com/api-reference/query-rewrite-management/delete-a-query-rewrite /api-reference/saas/cs-rules-rewrites.json delete /query-rewrites/{id} Delete a query rewrite. # Get a query rewrite Source: https://doc.lucidworks.com/api-reference/query-rewrite-management/get-a-query-rewrite /api-reference/saas/cs-rules-rewrites.json get /query-rewrites/{id} Retrieve a query rewrite. # List query rewrites Source: https://doc.lucidworks.com/api-reference/query-rewrite-management/list-query-rewrites /api-reference/saas/cs-rules-rewrites.json get /query-rewrites Note that sorting applies to the rule's staging content only. Filtering applies OR logic, so it matches if either the staging or live content matches the filter. Use `textSearchRelevance` sort to sort by search relevance (cannot be combined with other sort parameters). # Update a query rewrite Source: https://doc.lucidworks.com/api-reference/query-rewrite-management/update-a-query-rewrite /api-reference/saas/cs-rules-rewrites.json put /query-rewrites/{id} Update a query rewrite. # Request Access Token Source: https://doc.lucidworks.com/api-reference/request-access-token/request-access-token /api-reference/saas/authentication.json post /oauth2/{auth}/v1/token Use this API to generate an access token. # Get results by chunkingId Source: https://doc.lucidworks.com/api-reference/request-chunked-content/get-results-by-chunkingid /api-reference/saas/machine-learning-platform-async-chunking.json get /ai/async-chunking/{CHUNKING_ID} Fetch chunked content by chunking ID. The ID is returned in the response of the `POST` operation you used to trigger the chunking operation. # Create a rule Source: https://doc.lucidworks.com/api-reference/rule-management/create-a-rule /api-reference/saas/cs-rules-rewrites.json post /em-rules Create a rule in Commerce Studio. # Delete a rule Source: https://doc.lucidworks.com/api-reference/rule-management/delete-a-rule /api-reference/saas/cs-rules-rewrites.json delete /em-rules/{id} Delete a rule. # Get a rule Source: https://doc.lucidworks.com/api-reference/rule-management/get-a-rule /api-reference/saas/cs-rules-rewrites.json get /em-rules/{id} Retrieve a rule. # List rules Source: https://doc.lucidworks.com/api-reference/rule-management/list-rules /api-reference/saas/cs-rules-rewrites.json get /em-rules List all rules with optional filtering and pagination. Note that sorting applies to the rule's staging content only. Filtering applies OR logic, matching if either the staging or live content matches the filter. Use `textSearchRelevance` sort to sort by search relevance (cannot be combined with other sort parameters). # Update a rule Source: https://doc.lucidworks.com/api-reference/rule-management/update-a-rule /api-reference/saas/cs-rules-rewrites.json put /em-rules/{id} Update a rule. # Chunk text using the specified chunker Source: https://doc.lucidworks.com/api-reference/split-content-into-chunks/chunk-text-using-the-specified-chunker /api-reference/saas/machine-learning-platform-async-chunking.json post /ai/async-chunking/{CHUNKER}/{MODEL_ID} This is an all-purpose chunking endpoint you can use by specifying the `chunker` and `modelId` to use. The `POST` request submits text to be split into chunks based on the `CHUNKER` (chunking strategy) and `MODEL_ID` sent in the request. The API responds with the following information: * `chunkingId` that is a unique UUID for the submitted chunking task, and can be used later to retrieve the results. * `status` that indicates the current state of the chunking task. IMPORTANT: The available use cases by `chunker` are detailed in their own section in this specification. # Chunk using dynamic-sentence Source: https://doc.lucidworks.com/api-reference/split-content-into-chunks/chunk-using-dynamic-sentence /api-reference/saas/machine-learning-platform-async-chunking.json post /ai/async-chunking/dynamic-sentence/{MODEL_ID} The dynamic-sentence chunker (chunking strategy) splits the provided text into sentences. Sentences are joined until they reach the `maxChunkSize`. If `overlapSize` is provided, adjacent chunks will both have overlapping sentences on the sides. # Chunk using semantic chunker Source: https://doc.lucidworks.com/api-reference/split-content-into-chunks/chunk-using-semantic-chunker /api-reference/saas/machine-learning-platform-async-chunking.json post /ai/async-chunking/semantic/{MODEL_ID} The semantic chunker (chunking strategy) creates chunks based on semantic similarity. Using the model defined in the URL request, the semantic chunker splits text into sentences, encodes the sentences, and then compares the sentence to the building chunk to determine if they are similar enough to group together. After merging two semantically-similar sentences into a pre-chunk, the semantic chunker needs to encode it to get its vector to compare with the next sentence vector. This chunker is the slowest of all of the chunkers even if you set the `approximate` field to true. # Split text on a regex Source: https://doc.lucidworks.com/api-reference/split-content-into-chunks/split-text-on-a-regex /api-reference/saas/machine-learning-platform-async-chunking.json post /ai/async-chunking/regex-splitter/{MODEL_ID} The regex-splitter chunker (chunking strategy) splits the submitted text based on the specified regex (regular expression), according to the conventions employed by the `re` python package. For more information about the `re` operations, see https://docs.python.org/3/library/re.html. # Split text on newlines Source: https://doc.lucidworks.com/api-reference/split-content-into-chunks/split-text-on-newlines /api-reference/saas/machine-learning-platform-async-chunking.json post /ai/async-chunking/dynamic-newline/{MODEL_ID} The dynamic-newline chunker (chunking strategy) splits the provided text on all new line characters. Then all of the split chunks under the `maxChunkSize` limit will be merged. # Split text on sentences Source: https://doc.lucidworks.com/api-reference/split-content-into-chunks/split-text-on-sentences /api-reference/saas/machine-learning-platform-async-chunking.json post /ai/async-chunking/sentence/{MODEL_ID} The sentence chunker (chunking strategy) splits text on sentences. # Get use cases Source: https://doc.lucidworks.com/api-reference/use-cases/get-use-cases /api-reference/saas/machine-learning-platform-use-case.json get /ai/usecase Fetch the list of supported use cases with related models. # Deprecations and Removals Source: https://doc.lucidworks.com/docs/5/fusion/deprecations-and-removals [localhost link]: http://localhost:3000/docs/5/fusion/release-notes/deprecations-and-removals [mintlify link]: https://doc.lucidworks.com/docs/5/fusion/release-notes/deprecations-and-removals [old doc.lw link]: https://doc.lucidworks.com/fusion/5.9/8855 This document provides a comprehensive list of deprecated and removed features in Fusion, organized by version. It includes details on the deprecation and expected removal of various features, along with notes on alternatives or replacements where applicable. The document also contains links to relevant documentation for further information. The deprecations section lists features scheduled for removal in future releases, and the removals section lists features already removed in past releases. Each entry includes the feature name, the version in which it was deprecated or removed, and relevant notes or recommended replacements. The deprecation schedule outlined in this document applies exclusively to Fusion 5. Other major versions of Fusion have separate deprecation schedules not covered by this document. > [!TIP] > > Fusion Connectors deprecations and removals > > Deprecation and removal details for Fusion Connectors are found at [Fusion Connectors Deprecations and Removals](/docs/fusion-connectors/deprecations-and-removals). ## Deprecations Deprecated features in Fusion 5 are scheduled for removal in a future release. The following table lists each deprecated feature with an expected removal value, either a version number or a date. When a version number is specified, the feature will be removed in that specific release. When a date is specified, it represents the earliest possible day the feature will remain available. Removal will not occur before that date. > [!NOTE] > > **FAQ** > > When were these features originally deprecated? > > If a feature was originally deprecated in a prior version, the original deprecation version is noted in parentheses after the **Deprecated** version. ### Removing in Fusion 6.0 > **Apache Tika Parser** > > The [Apache Tika Parser](/docs/5/fusion/reference/config-ref/parser-stages/apache-tika-parser) is a versatile tool designed to support the parsing of numerous unstructured document formats. > > Use the [Tika Asynchronous Parser](/docs/5/fusion/getting-data-in/indexing/asynchronous-tika-parsing) instead. Asynchronous Tika parsing performs parsing in the background. This allows Fusion to continue indexing documents while the parser is processing others, resulting in improved indexing performance for large numbers of documents. > > Deprecated: All versions of 5.9.x (originally 5.8.0)Expected removal: 6.0.0 > **App Insights** > > [A tool within the Fusion workspace](/docs/5/fusion/getting-data-out/data-analytics/app-insights/overview) that provides real-time, searchable reports and visualizations from signals data. > > Deprecated: 5.9.13 (originally 5.12.0)Expected removal: 6.0.0 > **Banana Dashboards** > > [Banana](/docs/5/fusion/operations/monitoring-and-reporting/banana-dashboards/overview) serves as the underlying browser application for Fusion dashboards, enabling the creation of dynamic and interactive dashboards within Fusion. These dashboards support various data visualizations and user interactions. > > Deploy Banana Dashboards using a separate Docker deployment option, available in a future release. This approach provides continued support for users who rely on Banana Dashboards while allowing for independent management and updates outside of Fusion’s core deployment. > > Deprecated: 5.9.13 (originally 5.12.0)Expected removal: 6.0.0 > **Content-Based Recommender Job** > > The [Content-Based Recommender job](/docs/5/fusion/reference/config-ref/jobs/content-based-recommender) computes item-to-item similarities based on content fields, such as product descriptions. > > Deprecated: 5.19.0Expected removal: 6.0.0 > **Data Augmentation Job** > > The [Data Augmentation Job](/docs/5/fusion/reference/config-ref/jobs/data-augmentation) is designed to enhance training and testing data for machine learning models by increasing data quantity and introducing textual variations. It performs tasks such as backtranslation, synonym substitution, keystroke misspelling, and split word tasks. > > Deprecated: 5.9.13 (originally 5.12.0)Expected removal: 6.0.0 > **Domain-Specific Language (DSL)** > > The [Domain Specific Language (DSL)](/docs/5/fusion/getting-data-out/query-basics/domain-specific-language) in Fusion is designed to simplify the complexity of crafting search queries. It allows users to express complex search queries without needing to understand the intricate syntax required by the legacy Solr parameter format. > > Avoid using the Domain-Specific Language (DSL) feature, as it may cause performance degradation. Instead, use the [DSL to Legacy Parameters](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/dsl-to-legacy-query-stage) query pipeline stage to convert DSL requests to the legacy Solr format while maintaining compatibility. > > Deprecated: 5.9.4Expected removal: 6.0.0 > **Field Parser Index Stage** > > The [Field Parser index pipeline stage](/docs/5/fusion/reference/config-ref/pipeline-stages/index-stages/field-parser-index-stage) in Fusion is designed to parse content embedded within fields of documents. This stage operates separately from the parsers that handle whole documents. > > Use the [Tika Asynchronous Parser](/docs/5/fusion/getting-data-in/indexing/asynchronous-tika-parsing) instead. Asynchronous Tika parsing performs parsing in the background. This allows Fusion to continue indexing documents while the parser is processing others, resulting in improved indexing performance for large numbers of documents. > > Deprecated: All versions of 5.9.x (originally 5.8.0)Expected removal: 6.0.0 > **fusion-classification service** > > The `fusion-classification` service runs classification models in the Fusion cluster. > > Deprecated: 5.19.0Expected removal: 6.0.0 > **gRPC ml-model-service API** > > The gRPC API of the [ML Model service](/docs/5/fusion/dev-portal/api/ml-model-service/overview), which Fusion uses to call deployed machine learning models. > > Deprecated: 5.19.0Expected removal: 6.0.0 > **Head/Tail Analysis** > > Perform [head/tail analysis](/docs/5/fusion/reference/config-ref/jobs/head-tail-analysis) of queries from collections of raw or aggregated signals, to identify underperforming queries and the reasons. > > Instead, use [Neural Hybrid Search](/docs/5/fusion/hybrid-search/overview) for superior relevance compared to this legacy machine learning method. > > Deprecated: 5.9.15Expected removal: 6.0.0 > **Hybrid Query (5.9.9 and earlier)** > > A [stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/hybrid-search-query) to perform hybrid lexical-semantic search that combines BM25-type lexical search with KNN dense vector search via Solr. > > Use [Neural Hybrid Query Stage (5.9.10 and later)](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/neural-hybrid-query) instead to benefit from updates and improvements to the search capabilities of the stage. > > Deprecated: 5.9.13Expected removal: 6.0.0 > **Legacy Admin UI** > > The legacy Admin UI is the previous interface for managing Fusion apps and objects. > > Use the [new Admin UI](/docs/5/fusion/new-fusion-ui) instead. > > Deprecated: 5.19.0Expected removal: 6.0.0 > **Logistic Regression Classifier Training Jobs** > > This [job](/docs/5/fusion/reference/config-ref/jobs/logistic-regression-classifier-training) trains a logistic regression model with regularization to classify text into different categories. > > Deprecated: All versions of 5.9.x (originally 5.2.0)Expected removal: 6.0.0 > **Milvus Ensemble Query Stage** > > The [Milvus Ensemble Query stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/milvus-ensemble-query-stage) is used to enhance search results by incorporating vector-based similarity scoring. > > Replace the Milvus Ensemble Query Stage with the [Ray/Seldon Vectorize Query stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/vectorize-query-via-seldon-query-stage) with a Ray model for custom models, or with the [Lucidworks AI vector query stages](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/lwai-vectorize-query) for models hosted by Lucidworks AI. These alternatives improve vector search integration and support within Fusion’s evolving AI and machine learning capabilities. > > Deprecated: 5.9.5Expected removal: 6.0.0 > **Milvus Query Stage** > > The [Milvus Query stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/milvus-query-stage) performs vectors similarity search in Milvus, an open source vector similarity search engine integrated into Fusion to streamline its deep learning capabilities and reduce the workload on Solr. > > Replace the Milvus Query Stage with the [Ray/Seldon Vectorize Query stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/vectorize-query-via-seldon-query-stage) with a Ray model for custom models, or with the [Lucidworks AI vector query stages](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/lwai-vectorize-query) for models hosted by Lucidworks AI. These options enhance query efficiency and provide broader support for machine learning-driven search. > > Deprecated: 5.9.5Expected removal: 6.0.0 > **Milvus Response Update Query Stage** > > The [Milvus Response Update stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/milvus-response-update-stage) is designed to update response documents with vectors similarity and ensemble scores. > > Replace the Milvus Response Update Query Stage with the [Ray/Seldon Vectorize Query stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/vectorize-query-via-seldon-query-stage) with a Ray model for custom models, or with the [Lucidworks AI vector query stages](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/lwai-vectorize-query) for models hosted by Lucidworks AI. These alternatives improve performance when updating response documents with vector similarity data. > > Deprecated: 5.9.5Expected removal: 6.0.0 > **Parsers Indexing CRUD API** > > The [Parsers API](/api-reference/parsers-crud-api/list-all-parsers) provides CRUD operations for parsers, allowing users to create, read, update, and delete parsers. > > A new API introduced in Fusion 5.12.0, Async Parsing API, will replace the Parsers Indexing CRUD API and will be backported to Fusion 5.9.x. This API provides improved functionality and aligns with Fusion’s updated architecture, ensuring consistency across versions. > > Deprecated: 5.9.11 (originally 5.12.0)Expected removal: 6.0.0 > **Phrase Extraction** > > [Identify multi-word phrases in signals](/docs/5/fusion/reference/config-ref/jobs/phrase-extraction). > > Instead, use [Neural Hybrid Search](/docs/5/fusion/hybrid-search/overview) for superior relevance compared to this legacy machine learning method. > > Deprecated: 5.9.15Expected removal: 6.0.0 > **Query-to-Query Collaborative Similarity Job** > > This [job](/docs/5/fusion/reference/config-ref/jobs/query-to-query-collaborative-similarity) uses SparkML’s Alternating Least Squares (ALS) to analyze past queries and find similarities between them. It helps recommend related queries or suggest relevant items based on previous searches. > > Switch to [Query-to-Query Session-Based Similarity jobs](/docs/5/fusion/reference/config-ref/jobs/query-to-query-session-based-similarity) instead of the Query-to-Query Collaborative Similarity Job. The new method improves performance and increases the coverage of query similarity calculations. > > Deprecated: All versions of 5.9.x (originally 5.2.0)Expected removal: 6.0.0 > **Random Forest Classifier Training Jobs** > > This [job](/docs/5/fusion/reference/config-ref/jobs/random-forest-classifier-training) trains a machine learning model using a random forest algorithm to classify text into different categories. > > Deprecated: All versions of 5.9.x (originally 5.2.0)Expected removal: 6.0.0 > **Reverse Search** > > [Reverse Search](/docs/lucidworks-search/04-move-data-in/index-pipeline/reverse-search) matches incoming documents to saved monitoring queries, so you don't need to rerun a query to find new documents. > > Deprecated: 5.19.0Expected removal: 6.0.0 > **Security Trimming Query Stage** > > The [Security Trimming query pipeline stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/security-trimming-query-stage) in Fusion is designed to restrict query resultsby matching security ACL metadata, ensuring that users only see results they are authorized to access. > > Replace the Security Trimming Query Stage with the [Graph Security Trimming Query Stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/security-trimming-graph-query-stage). The new method uses a single filter query across all data sources. > > Deprecated: 5.9.0Expected removal: 6.0.0 > **Seldon** > > Seldon Core serves machine learning models in the Fusion cluster. This includes the [Create Seldon Core Model Deployment job](/docs/5/fusion/reference/config-ref/jobs/create-seldon-core-model-deployment), the [Delete Seldon Core Model Deployment job](/docs/5/fusion/reference/config-ref/jobs/delete-seldon-core-model-deployment), and Seldon models in the [Ray/Seldon Vectorize Field](/docs/5/fusion/reference/config-ref/pipeline-stages/index-stages/vectorize-field-via-seldon-index-stage) and [Ray/Seldon Vectorize Query](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/vectorize-query-via-seldon-query-stage) stages. > > Use Ray to host custom models instead. Deploy models with the [Create Ray Model Deployment job](/docs/5/fusion/reference/config-ref/jobs/create-ray-model-deployment), then use them in the Ray/Seldon Vectorize Field and Ray/Seldon Vectorize Query stages. > > Deprecated: 5.19.0Expected removal: 6.0.0 > **Smart Answers Coldstart Training job** > > The [Smart Answers Coldstart Training job](/docs/5/fusion/reference/config-ref/jobs/smart-answers-coldstart-training) in Fusion is designed to help train models when there is no historical training data available. > > Use pre-trained models or the supervised training job instead of the Smart Answers Coldstart Training job. Pre-trained models eliminate the need for manual training when historical data is unavailable, while supervised training jobs offer greater flexibility in model customization. > > Deprecated: 5.9.13 (originally 5.12.0)Expected removal: 6.0.0 > **Smart Answers Evaluate Pipeline job** > > The [Smart Answers Evaluate Pipeline job](/docs/5/fusion/reference/config-ref/jobs/smart-answers-evaluate-pipeline) evaluates the performance of a Smart Answers pipeline. > > Deprecated: 5.19.0Expected removal: 6.0.0 > **Smart Answers Supervised Training job** > > The [Smart Answers Supervised Training job](/docs/5/fusion/reference/config-ref/jobs/smart-answers-supervised-training) trains a Smart Answers model on a supervised basis, with pre-trained or trained embeddings, and deploys the trained model to the ML Model Service. > > Deprecated: 5.19.0Expected removal: 6.0.0 > **Support for Nashorn Javascript engine** > > Fusion uses the [Nashorn engine](/docs/5/fusion/getting-data-in/indexing/index-pipelines/custom-javascript-index-stages#the-javascript-engine-used-by-fusion) JavaScript engine for the JavaScript index and query stages. > > Use the OpenJDK Nashorn JavaScript engine instead of the deprecated Nashorn JavaScript engine in Fusion. This ensures continued JavaScript execution compatibility in pipeline configurations. You can select the engine from a dropdown in the pipeline views or in the workbenches. > > Deprecated: 5.9.8Expected removal: 6.0.0 > **Synonym Detection** > > Used to [generate pairs of synonyms](/docs/5/fusion/reference/config-ref/jobs/synonym-detection) and pairs of similar queries. Two words are considered potential synonyms when they are used in a similar context in similar queries. > > Instead, use [Neural Hybrid Search](/docs/5/fusion/hybrid-search/overview) for superior relevance compared to this legacy machine learning method. > > Deprecated: 5.9.15Expected removal: 6.0.0 > **Token and Phrase Spell Correction** > > [Detect misspellings](/docs/5/fusion/reference/config-ref/jobs/token-and-phrase-spell-correction) in queries or documents using the numbers of occurrences of words and phrases. > > Instead, use [Neural Hybrid Search](/docs/5/fusion/hybrid-search/overview) for superior relevance compared to this legacy machine learning method. > > Deprecated: 5.9.15Expected removal: 6.0.0 > **Connectors fetcher property AccessControlFetcher** > > Connectors that support security filtering previously used separate fetchers for content and access control. One fetcher type is now used for both content and security fetching. `AccessControlFetcher` has been deprecated. > > Fetcher implementations that use `AccessControlFetcher` should instead use `ContentFetcher`. > > Deprecated: All versions of 5.9.x (originally 5.1.2)Expected removal: 6.0.0 > **Messaging Stage Configs** > > Deprecated: All versions of 5.9.x (originally 5.1.2)Expected removal: 6.0.0 > **MLeap deployments of SpaCy and SparkNLP** > > Use **Develop and Deploy a Machine Learning Model** instead. > > Deprecated: 5.9.10 (originally 5.2.0)Expected removal: 6.0.0 > **Webapps Service** > > The Webapps service provides an embedded instance of App Studio within each Fusion instance, simplifying the deployment process. > > Deploy App Studio Enterprise using the **Deploy App Studio Enterprise to a Fusion 5 Cluster (GKE)** instead of relying on the Webapps service. This method improves scalability and provides a more robust deployment approach for enterprise environments. > > Deprecated: 5.9.10 (originally 5.11.0)Expected removal: 6.0.0 > **Word2Vec Model Training Jobs** > > The [Word2Vec model training job](/docs/5/fusion/reference/config-ref/jobs/word2vec-model-training) trains a shallow neural model to generate vector embeddings for text data and stores the results in a specified output collection. It supports configurable parameters for input data, model tuning, featurization, and output settings. > > Deprecated: 5.9.11 (originally 5.2.0)Expected removal: 6.0.0 ### To be determined > **ALS Recommender Job** > > The [ALS Recommender job](/docs/5/fusion/reference/config-ref/jobs/als-recommender/overview) in Fusion AI is used to compute user recommendations or item similarities using a collaborative filtering recommender. > > Use the [BPR Recommender job](/docs/5/fusion/reference/config-ref/jobs/bpr-recommender) instead of the ALS Recommender job. The BPR Recommender job delivers better recommendation accuracy with a shorter runtime. > > Deprecated: All versions of 5.9.x (originally 5.2.0)Expected removal: Version TBD > **Time-based partitioning** > > [Time-based partitioning](/api-reference/collections/get-collection-partitions-status) in Fusion collections allows mapping to multiple Solr collections or partitions based on specific time ranges. > > Deprecated: All versions of 5.9.x (originally 5.2.0)Expected removal: Version TBD ## Removals This section lists features that have been removed in past releases of Fusion. Each entry includes the feature name, the version in which it was removed, and any relevant notes or replacement recommendations. ### Fusion 5.19 > **Static and dynamic security trimming** > > Static and dynamic security trimming was removed in 5.19.0. > > V2 connectors now support only graph-based security trimming. Custom connectors built on the static or dynamic security-trimming APIs must move to graph-based security trimming. > **Connectors ConfigsApi endpoints** > > Connectors `ConfigsApi` endpoints were removed in 5.19.0. > > Use the `DataSourcesApi` endpoints instead. ### Fusion 5.11 > **MLeap** > > MLeap was removed in 5.11.0. > > Use **Develop and Deploy a Machine Learning Model** instead. This method provides a more flexible and modern approach to deploying machine learning models. > **Subscriptions UI** > > Subscriptions UI was removed in 5.11.0. ### Fusion 5.10 > **Forked Apache Tika Parser** > > Forked Apache Tika Parser was removed in 5.10.0. > > The Forked Apache Tika Parser was replaced by the [Tika Asynchronous Parser](/docs/5/fusion/getting-data-in/indexing/asynchronous-tika-parsing). The asynchronous parser improves performance by handling document parsing more efficiently and scaling better for enterprise workloads. ### Fusion 5.9 > **Analytics Catalog Query Stage** > > Analytics Catalog Query Stage was removed in 5.9.15. > **Tika Server Parser** > > [Tika Server Parser](/docs/5/fusion/reference/config-ref/parser-stages/apache-tika-server) was removed in 5.9.12. > > Use the [Tika Asynchronous Parser](/docs/5/fusion/getting-data-in/indexing/asynchronous-tika-parsing) instead. Asynchronous Tika parsing performs parsing in the background. This allows Fusion to continue indexing documents while the parser is processing others, resulting in improved indexing performance for large numbers of documents. > **MLeap in Machine Learning models** > > MLeap in Machine Learning models was removed in 5.9.12. ### Fusion 5.7 > **NLP Annotator Index Stage** > > NLP Annotator Index Stage was removed in 5.7.0. > > To implement similar functionality, see the **Develop and Deploy a Machine Learning Model** guide, which provides an adaptable example. > **NLP Annotator Query Stage** > > NLP Annotator Query Stage was removed in 5.7.0. > > To implement similar functionality, see the **Develop and Deploy a Machine Learning Model** guide, which provides an adaptable example. > **OpenNLP NER Extraction Index Stage** > > OpenNLP NER Extraction Index Stage was removed in 5.7.0. > > To implement similar functionality, see the **Develop and Deploy a Machine Learning Model** guide, which provides an adaptable example. ### Fusion 5.6 > **Fusion SQL** > > Fusion SQL was removed in 5.6.1. > **Apache Pulsar** > > Apache Pulsar was removed in 5.6.0. > > Apache Pulsar was removed in Fusion 5.6.0 and replaced with Kafka. Kafka offers better scalability, reliability, and industry support for message streaming. > **Log Viewer & DevOps Center UI panel** > > Log Viewer & DevOps Center UI panel were removed in 5.6.0. > > These features were removed in Fusion 5.6.0 as they depended on Apache Pulsar, which has been replaced by Kafka. Users should transition to Kafka-based logging and monitoring solutions. > **Subscriptions API** > > Subscriptions API was removed in 5.6.0. > **Send to Message Bus Index Stage** > > Send to Message Bus Index Stage was removed in 5.6.0. ### Fusion 5.5 > **Jupyter** > > Jupyter was removed in 5.5.2. > **Superset** > > Superset was removed in 5.5.2. # Introduction to Fusion Source: https://doc.lucidworks.com/docs/5/fusion/intro/overview [localhost link]: http://localhost:3000/docs/5/fusion/intro/overview [mintlify link]: https://doc.lucidworks.com/docs/5/fusion/intro/overview [old doc.lw link]: https://doc.lucidworks.com/fusion/5.9/3210 Fusion combines the Apache Solr open source search engine with the distributed power of Apache Spark for artificial intelligence. Highly scalable, Fusion indexes and stores data for real-time discovery. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio > **[Fusion Basics](https://academy.lucidworks.com/paths/019a5b69-2d6e-7f7b-8ffa-f18163f1ffda)** > > The learning path for **Fusion Basics** focuses on the basic structure, essential components, and foundational concepts you’ll need to understand Fusion. # Fusion Apps Source: https://doc.lucidworks.com/docs/5/fusion/intro/ui-tour/fusion-apps [localhost link]: http://localhost:3000/docs/5/fusion/intro/ui-tour/fusion-apps [mintlify link]: https://doc.lucidworks.com/docs/5/fusion/intro/ui-tour/fusion-apps [old doc.lw link]: https://doc.lucidworks.com/fusion/5.9/179 *Fusion apps* provide tailored search functionality to specific groups of users. An app is a named set of linked *objects*, including collections, datasources, index and query pipelines, index and query profiles, parsers, and more. You can define security on a per-app basis using [roles](/docs/5/fusion/operations/security/access-control/roles) and [security realms](/docs/5/fusion/operations/security/access-control/security-realms). The **Create App** modal can be accessed by clicking Create App. When naming an app, the name must start with a letter and can include letters, numbers, dashes (`-`), or underscores (`_`), with a maximum length of 128 characters. **To edit an app, access the **Edit App** modal by clicking on the settings cog icon on the app tile. Click on the pencil icon by the app name in the modal to edit the app name.** Generally, you will create multiple apps for different purposes. You can view all of your apps in the launcher when you log in to the Fusion UI: ![Launcher](https://mintcdn.com/lucidworks/L5PMnIeZ03zhv8Ti/assets/images/5.6/launcher-1-56.png?fit=max\&auto=format\&n=L5PMnIeZ03zhv8Ti\&q=85\&s=38545558a2d60fa332211f570f514635) To enter the Fusion workspace for any app, click the app name. In the Fusion workspace, you can hover over ![](/assets/images/5.6/workspace-menu-apps-56.png) to switch to another app, create a new app, or return to the launcher: ![App picker](https://mintcdn.com/lucidworks/VKnUHJXP6sWH55ak/assets/images/5.6/workspace-app-picker-56.png?fit=max\&auto=format\&n=VKnUHJXP6sWH55ak\&q=85\&s=de97a7809a0393da5a7426675edf6687) > **[Fusion Applications and Collections](https://academy.lucidworks.com/fusion-applications-and-collections)** > > The course for **Fusion Applications and Collections** focuses on the features of Fusion apps and collections and best practices when working with them. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Learn more > **Create and manage Fusion apps** > > You can create, modify, and delete apps in the Fusion UI or with the Apps API. > > ## Manage apps in the Fusion UI > > ### Create an app > > Fusion prompts you to create an app the first time you log in. You can create additional apps at anytime from Fusion’s home page. > > 1. Log into Fusion and navigate to the home screen. > 2. Click **Create new app**. > > ![Welcome screen create app](https://mintcdn.com/lucidworks/sBy1WWIeb2aVbL1d/assets/images/5.9/welcome-screen-create-app.png?fit=max\&auto=format\&n=sBy1WWIeb2aVbL1d\&q=85\&s=d5c1b818f232678424988e589397d7d6) > 3. Enter a **Name**, **Description**, and select an **App tile color**. > > ![Create app](https://mintcdn.com/lucidworks/sBy1WWIeb2aVbL1d/assets/images/5.9/create-app-details.png?fit=max\&auto=format\&n=sBy1WWIeb2aVbL1d\&q=85\&s=e0e17ffc65178414b5a5d6386bf9dce1) > 4. Click **Create App**. > > ### Modify or delete an app > > 1. Log into Fusion and navigate to the home screen. > 2. Click the **Configure** icon on the app you want to modify or delete. > > ![App config button](https://mintcdn.com/lucidworks/sBy1WWIeb2aVbL1d/assets/images/5.9/launcher-app-config-hover.png?fit=max\&auto=format\&n=sBy1WWIeb2aVbL1d\&q=85\&s=15707ec049a5faf64fbdeb0b644abc65) > 3. To modify the app, click the edit icon ![Edit icon](https://mintcdn.com/lucidworks/sBy1WWIeb2aVbL1d/assets/images/5.9/app-edit-icon.png?fit=max\&auto=format\&n=sBy1WWIeb2aVbL1d\&q=85\&s=f725ecb17c8bf540a33a36d916967f30). > > ![Modify app details](https://mintcdn.com/lucidworks/sBy1WWIeb2aVbL1d/assets/images/5.9/modify-app-details.png?fit=max\&auto=format\&n=sBy1WWIeb2aVbL1d\&q=85\&s=37109663bd40196d6feae320d06e371a) > > 1. Edit the **Name** or **Description**. > 2. Click **OK**. > 4. To delete the app, click **Delete app**. > 1. A dialog box appears where you can choose which associated objects to delete or retain. Only objects not associated with other objects are displayed. All objects are selected by default. > 2. Click **Confirm**. > > ![Confirmation dialog](https://mintcdn.com/lucidworks/sBy1WWIeb2aVbL1d/assets/images/5.9/launcher-app-delete-dialog.png?fit=max\&auto=format\&n=sBy1WWIeb2aVbL1d\&q=85\&s=6af7b5b6a97d5f7a577527c04a5e3845) > > ## Manage apps with the Apps API > > ### Create an app > > ```bash wrap theme={"dark"} > curl -u USERNAME:PASSWORD -X POST -H 'Content-type: application/json' -d '{"id": "MyNewApp", "name":"My new app", "description":"A really really great new app"}' https://FUSION_HOST/api/apps > ``` > > ### Delete an app > > Run the following command, replacing `{id}` with the name of your app. This operation take about a minute to complete. > > ```bash theme={"dark"} > curl -u USERNAME:PASSWORD -X DELETE https://FUSION_HOST/api/apps/{id} > ``` > **Export a Fusion App** > > To export a Fusion app, you can use either the Fusion UI or the [Objects API](/api-reference/objects/get-objects-service-status). > > > [!TIP] > > > > To upgrade from one Fusion version to a 5.x version, see [Fusion 5 Upgrades](/docs/5/fusion/operations/fusion-5-upgrades) to migrate objects. > > ## Export an app with the Fusion UI > > 1. Navigate to the launcher. > 2. Hover over the app you want to export and click the Configure icon: > > ![App config button](https://mintcdn.com/lucidworks/L5PMnIeZ03zhv8Ti/assets/images/5.6/launcher-app-config-hover-56.png?fit=max\&auto=format\&n=L5PMnIeZ03zhv8Ti\&q=85\&s=8ae921d898899048020c96681719b4ee) > 3. In the app config window, click **Export app to zip**: > > ![Export app to zip](https://mintcdn.com/lucidworks/L5PMnIeZ03zhv8Ti/assets/images/5.6/launcher-export-app-56.png?fit=max\&auto=format\&n=L5PMnIeZ03zhv8Ti\&q=85\&s=198aa7f16fddd9adc758115e7ec132c2) > > To import the downloaded zip file into other instances of Fusion 5.x, see [Import a Fusion App](#import-a-fusion-app). > > ## Export an app with the Objects API > > The examples below show how to export one or more apps: > > **Export all apps** > > ```bash wrap theme={"dark"} > curl -u USERNAME:PASSWORD http://localhost:6764/api/objects/export?type=app > all-apps.zip > ``` > > **Get all app IDs, then export one app by ID** > > ```bash expandable theme={"dark"} > > curl -u USERNAME:PASSWORD http://localhost:6764/api/apps > > [ { > "id" : "movies", > "name" : "Movies", > "description" : "Search the movielens database.", > "dataUri" : "/App-Tile-01-460x160.png", > "properties" : { > "headerImageName" : "headerImage1", > "tileColor" : "apps-darkblue", > "previousCollectionId" : "movies" > } > }, { > "id" : "tech-pubs", > "name" : "TechPubs", > "description" : "Search the documentation.", > "dataUri" : "/App-Tile-02-460x160.png", > "properties" : { > "headerImageName" : "headerImage2", > "tileColor" : "apps-darkblue", > "previousCollectionId" : "tech-pubs" > } > } ] > > > curl -u USERNAME:PASSWORD http://localhost:6764/api/objects/export?app.ids=tech-pubs > techpubs.zip > ``` > > > [!NOTE] > > > > When you export an app that includes objects that are shared with other apps, then all apps linked to that object are also exported. > > **Export two apps by ID** > > ```bash wrap theme={"dark"} > curl -u USERNAME:PASSWORD http://localhost:6764/api/objects/export?app.ids=tech-pubs,movies > two-apps.zip > ``` > > > [!TIP] > > > > For the `app` object type, the `deep` parameter is not used. Linked objects are always included when exporting apps. > **Import a Fusion App** > > To import an app, you can use either the Fusion UI or the [Objects API](/api-reference/objects/import-objects). > > ## Import an app with the Fusion UI > > 1. Navigate to the launcher. > 2. Click **Import app**. > > ![Import app](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/launcher-import-app.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=c093d9e28cc5ab76f2c4a7323d741afa) > 3. Under **Data File**, click **Choose File** and select the zip file containing the app you want to import. > 4. If your app has usernames and passwords in a separate file, select it under **Variables File**. > If the Variables File is needed, it *must* be a separate file that is not in a .zip file. It is a .json map of variables to values. The following is an example: > ```json theme={"dark"} > { > "secret.dataSources.Inventory_BR_S3_DS.password":"SOMETHING", > "secret.dataSources.LLM_A_BR_S3_DS.password":"FmJSaDE9Tj5REDACTED", > "secret.dataSources.LLM_BR_Inventory_S3_DS.password":"FmJSaDE9Tj5GzIVvethAC4Huh", > "secret.dataSources.LLM_BR_Load_S3_DS.password":"FmJSaDE9Tj5GzIVvethAC4" > } > ``` > 5. You can sometimes edit parameter values to use the new values in the imported app. If this is the case, Fusion displays a dialog box that lets you edit the parameter values. > > ![Edit parameter values](https://mintcdn.com/lucidworks/de_1M1m_4TTyJqw0/assets/images/5.0/import-app-edit-parameters.png?fit=max\&auto=format\&n=de_1M1m_4TTyJqw0\&q=85\&s=2211f3a81b3394a7959b582d59afa2b9) > > Make desired changes, and then click **Import**. > > ## Import an app with the Objects API > > Like any other Fusion object, an exported app is contained in a zip file which Fusion can consume upon import. The zip file does not need to be expanded first. > > **Import objects from a file and stop if there are conflicts** > > ```bash wrap theme={"dark"} > curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'importData=@/Users/admin/Fusion/export.zip' http://localhost:6764/api/objects/import?importPolicy=abort > ``` > > **Import objects, substitute the password variables, and merge any conflicts** > > ```bash wrap theme={"dark"} > curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'importData=@/Users/admin/Fusion/export.zip' -F 'variableValues=@password_file.json' http://localhost:6764/api/objects/import?importPolicy=merge > ``` > > > [!NOTE] > > > > `password_file.json` must contain plaintext passwords. > > **Import a zip file of Fusion objects and merge any conflicts** > > ```bash wrap theme={"dark"} > curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'importData=@/Users/admin/Fusion/techpubs.zip' http://localhost:6764/api/objects/import?importPolicy=merge > ``` > **Import objects into an app** > > You can import exported Fusion objects into the currently open app. > > 1. In the Fusion launcher, click the app into which you want to import objects. > The Fusion workspace appears. > 2. Click **System > Import Fusion Objects**. > The Import Fusion Objects window opens. > > ![Import Objects Window](https://mintcdn.com/lucidworks/NgNm7Bp5nEBDIA7H/assets/images/4.0/import-objects.png?fit=max\&auto=format\&n=NgNm7Bp5nEBDIA7H\&q=85\&s=04697d36b39bd2229b87bedfee422a09) > 3. Select the data file from your local filesystem. > If you are importing [usernames and passwords](/api-reference/objects/import-objects) in a separate file, select it under **Variables File**. > 4. Click **Import**. > If there are conflicts, Fusion prompts you to specify an import policy: > > ![Import Conflicts](https://mintcdn.com/lucidworks/NgNm7Bp5nEBDIA7H/assets/images/4.0/import-conflicts.png?fit=max\&auto=format\&n=NgNm7Bp5nEBDIA7H\&q=85\&s=53b711be62ea740fb033b6dbc96a29a6) > > * Click **Overwrite** to overwrite the objects on the target system with the ones in the import file. > * Click **Merge** to skip all conflicting objects and import only the non-conflicting objects. > * Click **Start Over** to abort the import. > Fusion confirms that the import was successful: > > ![Successful Import](https://mintcdn.com/lucidworks/NgNm7Bp5nEBDIA7H/assets/images/4.0/import-objects-success.png?fit=max\&auto=format\&n=NgNm7Bp5nEBDIA7H\&q=85\&s=e2416d872ac6a74f2d40eaa4adbde56f) > 5. Click **Close** to close the Import Fusion Objects window. > **Add an object to an app** > > You can add objects present in other apps (or in no apps) to the open app. Some objects are linked to other apps. You can also add those directly to an app. > > * **Add an object to an app** – While in the Fusion workspace for the app to which you want to add an object, open Object Explorer and click **In Any App**. Search for or browse to the object you want to add. Hover over the object, click the App ![App](https://mintcdn.com/lucidworks/5yWZ-KtZuBe4Y_Fg/assets/images/4.0/icons/oe-app-menu.png?fit=max\&auto=format\&n=5yWZ-KtZuBe4Y_Fg\&q=85\&s=1e9322222ea76f70c278fb9c2a04ce9f) icon, and then click **Add to this app**. > > ![Add to this app](https://mintcdn.com/lucidworks/l9y7VqRhZkN9hmR0/assets/images/4.0/object-explorer-add-to-app.png?fit=max\&auto=format\&n=l9y7VqRhZkN9hmR0\&q=85\&s=472088e9361aa1bc278ad7da50e9bbdf) > * **Add an object to an app directly** – In cases when an object is linked to an app, but is not linked directly to the app (it is linked via some dependency), you can add the object to an app directly. > > While in the Fusion workspace for the app to which you want to add an object directly, open Object Explorer and click **In Any App**. Search for or browse to the object you want to add. Hover over the object, click the App ![App](https://mintcdn.com/lucidworks/5yWZ-KtZuBe4Y_Fg/assets/images/4.0/icons/oe-app-menu.png?fit=max\&auto=format\&n=5yWZ-KtZuBe4Y_Fg\&q=85\&s=1e9322222ea76f70c278fb9c2a04ce9f) icon, and then click **Add to this app directly**. > > ![Add to this app directly](https://mintcdn.com/lucidworks/l9y7VqRhZkN9hmR0/assets/images/4.0/object-explorer-add-directly-to-app.png?fit=max\&auto=format\&n=l9y7VqRhZkN9hmR0\&q=85\&s=af54840e096bbb4e6814c7eb5960d492) # Fusion UI Tour Source: https://doc.lucidworks.com/docs/5/fusion/intro/ui-tour/overview [localhost link]: http://localhost:3000/docs/5/fusion/intro/ui-tour/overview [mintlify link]: https://doc.lucidworks.com/docs/5/fusion/intro/ui-tour/overview [old doc.lw link]: https://doc.lucidworks.com/fusion/5.9/116 The Fusion UI gives you easy access to all Fusion features. The UI service utilizes the API service, so each UI feature has an API equivalent. For programmatic access to the features you see in the UI, see the [API Reference Guide](/docs/5/fusion/dev-portal/rest-apis). > **[Navigating the Fusion UI](https://academy.lucidworks.com/navigating-the-fusion-admin-ui)** > > The course for **Navigating the Fusion UI** focuses on navigating through the Fusion application. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio ## Logging in The Proxy service runs on port 6764 by default. Access the Fusion UI through the Proxy service. To log in, point your browser to this port on the Fusion host, for example, `http://FUSION_HOST:FUSION_PORT/`. When you are the *first user* to log in: Fusion prompts you to set the password for the "admin" account and agree to the license terms. All other accounts must be created by an admin. ![Set the admin password](https://mintcdn.com/lucidworks/L5PMnIeZ03zhv8Ti/assets/images/5.6/first-login-56.png?fit=max\&auto=format\&n=L5PMnIeZ03zhv8Ti\&q=85\&s=3e284619df277d07e23399d277c4f192) The first time you log in: Fusion opens the **Quickstart**, to give you a demonstration of Fusion’s most basic features. You can click **Exit the Quickstart** to close it and go to the Fusion launcher. > **Quickstart** > > The Quickstart is a wizard that lets you explore some of Fusion’s core capabilities: > > * Creating or selecting an app > > * Selecting a collection (where data is stored) > > * Indexing data > > * Searching > > > **[Using The Quickstart Wizard](https://academy.lucidworks.com/using-the-quickstart-guide)** > > > > The course for **Using The Quickstart Wizard** focuses on using the wizard to practice using the key functions of Fusion. > > ## Step through the Quickstart wizard > > If it is not already open, open the Quickstart wizard. In the Fusion launcher, click **New here? Get started...**. > > ![Quickstart](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/quickstart-0.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=329060363f0f5f90f8549d04c48d7ea3) > > 1. Click **Continue**. > > On the **Select an App** screen, you can select or create an [app](/docs/4/fusion-server/concepts/overview) for your quickstart data. > > ![quickstart-1](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/quickstart-1.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=4052bec5c555a091d209b2ce5532f1c2) > > If you click **Create new app**, Fusion prompts you to enter an app name (and optionally a description), then click **Create App** to return to the Quickstart. Your new app is selected by default. > 2. After selecting an app, click **Continue**. > > On the **Select a Collection** screen, you can select or create a [collection](/docs/4/fusion-server/concepts/overview) for your quickstart data. A collection with the same name as your app is created automatically: > > ![quickstart-2](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/quickstart-2.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=b8827c03f1fe2ad3098e2c2085eba784) > 3. Click **Continue**.\ > On the **Index Data** screen, you can either select one of the built-in sample datasets or click **Use my data** to upload your own: > > ![quickstart-3](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/quickstart-3.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=aadb5946967cccea0d40b5506e05d62c) > 4. Click **Continue**.\ > On the **Query Data** screen, you can see all search results and enter your own search queries to test the indexed dataset. You can also select the display fields or view the parsed documents: > > ![quickstart-4](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/quickstart-4.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=7f56764e53b2a70e236498f26f1d5e5d) > 5. Click **Continue**. > > ![quickstart-5](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/quickstart-5.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=f3f2322e0ae634f07e09dabc962edc6c) > > From here, you can do the following: > > * Open the Index Workbench to change the index pipeline. > * [Fusion 4.x Index Workbench](/docs/4/fusion-server/concepts/indexing/datasources/index-workbench) > * [Fusion 5.x Index Workbench](/docs/5/fusion/intro/ui-tour/index-workbench) > * Open the Query Workbench to change the query pipeline. > * [Fusion 4.x Query Workbench](/docs/4/fusion-server/concepts/querying/query-workbench) > * [Fusion 5.x Query Workbench](/docs/5/fusion/getting-data-out/query-basics/query-workbench) > > The workbenches are essentials tools in the Fusion workflow. > * Open [App Studio](/docs/4/app-studio/overview) to create a user interface for searching this collection. > > > [!NOTE] > > > > App Studio is only available in Fusion 4.1 and 4.2. You can open the Quickstart at any time by navigating to the Fusion launcher and clicking **New here? Get started…​**. ![Quickstart](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/quickstart-0.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=329060363f0f5f90f8549d04c48d7ea3) The brief tour below shows you how to find your way around the interface. For a more detailed tour, try the **Getting Started with Fusion Server** tutorial. > **Getting Started with Fusion Server** > > This tutorial takes you from installation to application-ready search data in four easy parts, using a [MovieLens](https://grouplens.org/datasets/movielens/) dataset. > > * Part 1: Run Fusion and Create an App > > Download, install Fusion, and run Fusion, then create a Movie Search app. > * Part 2: Get Data In > > Use the Index Workbench to configure an index pipeline, preview the results, and get data into the Movie Search app in a format that is useful for search. > * Part 3: Get Data Out > > Use Query Workbench to get data out of the Movie Search app, explore the role of query pipeline stages, configure faceting, and preview search results. > * Part 4: Improve Relevancy > > Use signals and boosting to make search results more relevant. ## A brief tour * The *launcher* is where you can view all apps in your Fusion environment and create new ones. * The *Fusion workspace* is where you configure how an app ingests, indexes, queries, and analyzes data. ### The Fusion launcher When you log in to Fusion, the first page is the Fusion launcher. This is where you create and launch apps: ![Launcher](https://mintcdn.com/lucidworks/L5PMnIeZ03zhv8Ti/assets/images/5.6/launcher-1-56.png?fit=max\&auto=format\&n=L5PMnIeZ03zhv8Ti\&q=85\&s=38545558a2d60fa332211f570f514635) To return to the Fusion workspace, hover over ![](/assets/images/5.6/workspace-menu-apps-56.png), and then click **Return to launcher**. See details about **Create an App**. > **Create an App** > > To create an app in App Studio: > > 1. Navigate to the launcher and click **Create new app**. > > ![Create a new app from the launcher](https://mintcdn.com/lucidworks/zH_ln2rWO5G9pvTA/assets/images/5.0/launcher-new-app.png?fit=max\&auto=format\&n=zH_ln2rWO5G9pvTA\&q=85\&s=c88bef361369ddaaca1f0e72b546ac1e) > 2. Enter an app name. > > Optionally, you can also enter a description and select the app tile color. > > If you want to choose the name of the first collection in the app, then deselect **Create new app default collection**. When you do this and click **Create app** (in the next step), Fusion Server prompts you to enter a name for the first collection. Otherwise, Fusion Server creates a default collection whose name is the same as the app name. > 3. Click **Create App**. > > The Fusion workspace appears, and you are ready to work with your app’s first collection. ### The Fusion workspace You can reach the Fusion workspace by clicking on any app in the launcher. When you enter the Fusion workspace, you find all the tools you need to configure the selected app: * On the left side are the [app tool menus](#app-tool-menus), where you can find tools for working with your app. * [System-wide tools](#system-wide) are at the top of the UI. With the exception of the **Collections** tool, which allows you to switch between collections for your app, these tools do not concern your app specifically. #### App tool menus ![alt](https://mintcdn.com/lucidworks/VKnUHJXP6sWH55ak/assets/images/5.6/ui-tour-part-1-56.png?fit=max\&auto=format\&n=VKnUHJXP6sWH55ak\&q=85\&s=1301efd121a93df8807a1880fec3cd04) On the left side of the screen are six menus where you can find tools for working with your app: 1. ![](/assets/images/5.6/workspace-menu-indexing-56.png) **Indexing** (getting data in)\ The [Index Workbench](/docs/5/fusion/intro/ui-tour/index-workbench) is the primary tool for getting data into your app through the Fusion UI. It provides an all-in-one view of the components of a datasource. You can also access those components individually through this menu. 2. ![](/assets/images/5.6/workspace-menu-querying-56.png) **Querying** (getting data out)\ For getting data out, the [Query Workbench](/docs/5/fusion/intro/ui-tour/query-workbench) is the main tool. It shows you a live preview of search results while you configure and fine tune your query pipelines.\ See also [Getting Data Out](/docs/5/fusion/getting-data-out/query-basics/overview). 3. ![](/assets/images/5.6/workspace-menu-collections-56.png) **Collections**\ Manage your data collections and configure their features.\ See also [Collection Management](/docs/5/fusion/getting-data-in/indexing/collections/overview). 4. ![](/assets/images/5.6/relevance-icon-56.png) **Relevance**\ Add or edit rules, recommendations, and signals. 5. ![](/assets/images/5.6/analytics-icon-56.png) **Analytics Hub**\ View App Insights, run Experiments, or view your Dashboard. 6. ![](/assets/images/5.6/system-icon-56.png) **System**\ Manage your system, including access control and logs. #### System-wide ![Top nav](https://mintcdn.com/lucidworks/VKnUHJXP6sWH55ak/assets/images/5.6/ui-tour-part-2-56.png?fit=max\&auto=format\&n=VKnUHJXP6sWH55ak\&q=85\&s=7779804341039755821f11fea9a493ae) On the right are menus for system-wide actions: 1. ![](/assets/images/5.6/workspace-menu-apps-56.png) **Apps**\ Switch between apps or return to the app launcher. 2. ![](/assets/images/5.6/collections-icon-56.png) **Collections**\ View and navigate to other collections. 3. ![](/assets/images/5.3/all-services-operational.png) **Microservices**\ View the status of all Fusion microservices. 4. ![](/assets/images/5.3/search-icon.png) **Search**\ Click the search icon and enter a query to find areas of the Fusion UI, objects, and related documentation. Clicking an object opens the [Object Explorer](/docs/5/fusion/intro/ui-tour/object-explorer). 5. ![](/assets/images/4.0/icons/workspace-help.png) **Help**\ Access the documentation. 6. ![](/assets/images/4.0/icons/workspace-alerts.png) **Alerts**\ New alerts are briefly displayed in the foreground. Open this menu to see past alerts, or to clear the alert history. 7. ![](/assets/images/4.0/icons/workspace-account.png) **Account Settings**\ Edit your profile, log out, or manage your Fusion license. # Try the New Admin UI Source: https://doc.lucidworks.com/docs/5/fusion/new-fusion-ui Fusion 5.19 introduces a redesigned Admin UI, rebuilt on React to replace the legacy AngularJS interface. It brings updated navigation and a modern visual style. [Try the New Fusion Admin UI](https://app.supademo.com/embed/cmunbiv6h002a000jchu13ohd?embed_v=2\&utm_source=embed) > [!NOTE] > > The new Admin UI is a preview. > Some capabilities may not be available yet, and screen locations may change before general availability. ## What's changing The new UI uses the screen more efficiently and helps you see where you are and what matters. A labeled sidebar groups screens by area, replacing the icon menus and their flyouts, and a breadcrumb in the header shows your location. Every screen is one click away and opens in place, instead of stacking up as tabs along the bottom of the window. Content fills the page in clearly separated panels, and size, color, and grouping draw your eye to what's important, such as summary figures with trend lines and color-coded object types. ![New UI](/assets/images/5.19/new-ui/new-consumption.png) New UI ![Legacy UI](/assets/images/5.19/new-ui/old-consumption.png) Legacy UI Drag to compare the legacy and new Admin UI In addition to the overall new look and feel throughout the Admin UI, several screens offer an improved experience. ### Clearer Object Explorer Object Explorer now groups objects by type and color-codes each type, so you can tell datasources, pipelines, and collections apart at a glance. Select an object to see its linked objects in a panel next to the list, instead of switching between the list and a separate links view. ![New UI](/assets/images/5.19/new-ui/new-object-explorer.png) New UI ![Legacy UI](/assets/images/5.19/new-ui/old-object-explorer.png) Legacy UI Drag to compare the legacy and new Object Explorer ### Status and details at a glance Lists such as datasources, jobs, and pipelines are now tables that show key information for every object, so you don't have to open each one. Status labels show which datasources are running and which jobs succeeded or failed, so you can see what needs attention. Select a row to see its details and actions, such as **Stop**, **Edit**, or **Delete**, in a panel next to the table. A notifications panel collects events such as failed queries, stopped jobs, and finished datasource runs. ![New UI](/assets/images/5.19/new-ui/new-datasources-running.png) New UI ![Legacy UI](/assets/images/5.19/new-ui/old-datasources.png) Legacy UI Drag to compare the legacy and new Datasources screen ### Visual stage explanations When you select a stage in Index Workbench, Query Workbench, or a parser, a diagram at the top of its configuration panel shows what the stage does. It traces a sample input through the stage to the result, such as the boost that the Boost with Signals stage adds from click signals. Each stage in the pipeline list also shows a short description, so you can see what a stage does without opening it. ![The Boost with Signals stage diagram traces a query through the stage to a query boosted by click signals](https://mintcdn.com/lucidworks/3A93rNqzJvLMwosd/assets/images/5.19/new-ui-workbench-stage-diagram.png?fit=max\&auto=format\&n=3A93rNqzJvLMwosd\&q=85\&s=5dc18c018d4f1741be6aac18aa41ed4f) ### More detailed jobs catalog Browse all available job types in a more detailed catalog with full descriptions to help you find the right job type.