> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recommend Items for User Stage

export const schema = {
  "type": "object",
  "title": "Recommend Items for User",
  "description": "This stage uses user recommendations for search time boosting",
  "required": ["boostingMethod", "boostingParam"],
  "properties": {
    "skip": {
      "type": "boolean",
      "title": "Skip This Stage",
      "description": "Set to true to skip this stage.",
      "default": false,
      "hints": ["advanced"]
    },
    "label": {
      "type": "string",
      "title": "Label",
      "description": "A unique label for this stage.",
      "hints": ["advanced"],
      "maxLength": 255
    },
    "condition": {
      "type": "string",
      "title": "Condition",
      "description": "Define a conditional script that must result in true or false. This can be used to determine if the stage should process or not.",
      "hints": ["code", "code/javascript", "advanced"]
    },
    "numRecommendations": {
      "type": "integer",
      "title": "Number of Recommendations",
      "default": 10
    },
    "modelID": {
      "type": "string",
      "title": "Model ID",
      "default": "*"
    },
    "collection": {
      "type": "string",
      "title": "Recommendation Collection",
      "description": "If left blank, the default recommendation collection for the collection being queried will be used."
    },
    "resultsLocation": {
      "type": "string",
      "title": "Results Location",
      "description": "If As Response is chosen, then the result of the RPC call will be the one and only response.  In all other cases, the stage will put the response from the REST/RPC call into the target location using the resultsKey. ",
      "enum": ["As Boosts", "As Response"],
      "default": "As Boosts"
    },
    "modelIdField": {
      "type": "string",
      "title": "Model ID Field",
      "description": "the name of the field in the recommendation collection where model ID is stored",
      "default": "modelId",
      "hints": ["advanced"]
    },
    "scaleRange": {
      "type": "object",
      "title": "Scale Boosts",
      "description": "Scale the boost values to a [min,max] range",
      "required": ["scaleMin", "scaleMax"],
      "properties": {
        "scaleMin": {
          "type": "number",
          "title": "Minimum value of the scale range"
        },
        "scaleMax": {
          "type": "number",
          "title": "Maximum value of the scale range"
        }
      },
      "hints": ["advanced"]
    },
    "foldInUpdates": {
      "type": "boolean",
      "title": "Estimate Recent Results",
      "description": "Update recommendations based on user activity that has happened since the last recommendation job run",
      "hints": ["advanced"]
    },
    "boostFieldName": {
      "type": "string",
      "title": "Boost Field",
      "description": "The field name to boost the values on.",
      "default": "id",
      "hints": ["advanced"]
    },
    "boostingMethod": {
      "type": "string",
      "title": "Boost Method",
      "description": "The boost method to use. query-parser should be chosen if defType!=edismax for main query.",
      "enum": ["query-param", "query-parser"],
      "default": "query-param",
      "hints": ["advanced"]
    },
    "boostingParam": {
      "type": "string",
      "title": "Boost Param",
      "description": "’Boost' multiplies scores by the boost values whereas 'bq' adds optional clauses to main query.",
      "enum": ["boost", "bq"],
      "default": "boost",
      "hints": ["advanced"]
    },
    "userIdParam": {
      "type": "string",
      "title": "User ID Request Parameter",
      "description": "The name of the request parameter containing the user ID",
      "default": "user_id"
    },
    "userIdField": {
      "type": "string",
      "title": "User ID Field",
      "description": "the name of the field in the recommendation collection where user ID is stored",
      "default": "userId",
      "hints": ["advanced"]
    },
    "itemIdField": {
      "type": "string",
      "title": "Item ID Field",
      "description": "the name of the field in the recommendation collection where item ID is stored",
      "default": "itemId",
      "hints": ["advanced"]
    },
    "weightField": {
      "type": "string",
      "title": "Weight Field",
      "description": "the name of the field in the recommendation collection where weight of the recommendation is stored",
      "default": "weight",
      "hints": ["advanced"]
    },
    "modelCollection": {
      "type": "string",
      "title": "Model Collection ID",
      "description": "The name of the collection where models are stored. By default this is {app_name}_recommender_models",
      "hints": ["advanced"]
    },
    "rawSignalsCollection": {
      "type": "string",
      "title": "Signals Collection",
      "description": "The collection to use to fetch recent user interactions, if 'Estimate Recent Results' is true.",
      "hints": ["advanced"]
    }
  },
  "category": "Results Relevancy",
  "categoryPriority": 6,
  "unsafe": false
};

export const SchemaParamFields = ({schema}) => {
  const sanitize = str => {
    if (typeof str !== "string") return str;
    return str.replace(/^"(.*)"$/s, "$1").replace(/\\/g, "").replace(/"/g, "'");
  };
  const renderMd = str => {
    const s = sanitize(str);
    const text = (/[.!?]\)*$/).test(s) ? s : `${s}.`;
    return text.split(/(\*\*[^*]+\*\*|_[^_]+_|`[^`]+`)/g).map((part, i) => {
      if (part.startsWith("**")) return <strong key={i}>{part.slice(2, -2)}</strong>;
      if (part.startsWith("_")) return <em key={i}>{part.slice(1, -1)}</em>;
      if (part.startsWith("`")) return <code key={i}>{part.slice(1, -1)}</code>;
      return part;
    });
  };
  const {description, properties = {}, required: requiredProps = []} = schema;
  const visibleProps = useMemo(() => Object.entries(properties).filter(([, prop]) => !prop.hints?.includes("hidden")), [properties]);
  const renderProp = ([name, prop]) => {
    const isRequired = requiredProps.includes(name);
    const hasDefault = prop.default !== undefined;
    const rawDefault = prop.default;
    const hints = prop.hints || [];
    const isComplexDefault = hasDefault && (typeof rawDefault === "object" || typeof rawDefault === "string" && (rawDefault.length > 20 || rawDefault.includes('"')));
    const postBadges = [];
    if (prop.title) {
      postBadges.push(<><span className="text-stone-400 dark:text-stone-500">API property: </span>{name}</>);
    }
    const constraints = [];
    if (prop.minimum !== undefined && prop.maximum !== undefined) {
      constraints.push(`Range: ${prop.minimum} – ${prop.maximum}`);
    } else if (prop.minimum !== undefined) {
      constraints.push(`Min: ${prop.minimum}`);
    } else if (prop.maximum !== undefined) {
      constraints.push(`Max: ${prop.maximum}`);
    }
    if (prop.minLength !== undefined && prop.maxLength !== undefined) {
      constraints.push(`Length: ${prop.minLength} – ${prop.maxLength}`);
    } else if (prop.minLength !== undefined) {
      constraints.push(`Min length: ${prop.minLength}`);
    } else if (prop.maxLength !== undefined) {
      constraints.push(`Max length: ${prop.maxLength}`);
    }
    const fieldProps = {
      key: name,
      body: prop.title || name,
      type: prop.type,
      ...postBadges.length > 0 && ({
        post: postBadges
      }),
      ...isRequired && ({
        required: true
      }),
      ...!isComplexDefault && hasDefault ? {
        default: sanitize(String(rawDefault))
      } : {}
    };
    const isObject = prop.type === "object" && prop.properties;
    const isArrayOfObjects = prop.type === "array" && prop.items?.type === "object" && prop.items.properties;
    return <ParamField {...fieldProps}>
        {prop.description && <p>{renderMd(prop.description)}</p>}

        {prop.enum && <p>
            Allowed values: 
            {prop.enum.map((v, i) => <>{i > 0 && ", "}<code key={i}>{String(v)}</code></>)}
          </p>}

        {constraints.length > 0 && <p className="text-stone-500 dark:text-stone-400 text-sm">
            {constraints.join(" · ")}
          </p>}

        {isComplexDefault && <div className="flex">
            <p>
              <strong>Default:</strong>
            </p>
            <pre className="!my-0">
              <code>
                {JSON.stringify(rawDefault, null, 2)}
              </code>
            </pre>
          </div>}

        {isArrayOfObjects && <Expandable title="item properties">
            <SchemaParamFields schema={{
      properties: prop.items.properties,
      required: prop.items.required
    }} />
          </Expandable>}

        {isObject && <Expandable title="properties">
            <SchemaParamFields schema={{
      properties: prop.properties,
      required: prop.required
    }} />
          </Expandable>}
      </ParamField>;
  };
  return <div>
      {description && <p>{renderMd(description)}</p>}

      {visibleProps.map(renderProp)}
    </div>;
};

export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => {
  const [isLoaded, setIsLoaded] = useState(false);
  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, 500);
    return () => clearTimeout(timer);
  }, []);
  return <div className="lw-template-container">
      <Card title={title} icon={icon}>
        {isLoaded && <span dangerouslySetInnerHTML={{
    __html: `<lw-template id="a029c1a9-28be-427e-b0e1-5d918920246a"></lw-template
            >`
  }} />}
        <Link href={linkHref} className="agent-studio-link text-left text-gray-600 gap-2 dark:text-gray-400 text-sm font-medium flex flex-row items-center hover:text-primary dark:hover:text-primary-light group-hover:text-primary group-hover:dark:text-primary-light">Powered by Lucidworks Agent Studio</Link>
      </Card>
    </div>;
};

[localhost link]: http://localhost:3000/docs/4/fusion-server/reference/pipeline-stages/query/recommend-items-for-user-query-stage

[mintlify link]: https://doc.lucidworks.com/docs/4/fusion-server/reference/pipeline-stages/query/recommend-items-for-user-query-stage

[old doc.lw link]: https://doc.lucidworks.com/fusion-server/4.2/281

The Recommend Items for User query pipeline stage uses signals about item choices to recommend other similar items for a specific user. Personalization for the user can be based on the user’s search history, browsing history, or purchase history, and so on.

This pipeline stage uses items-for-user recommendations that have been precomputed by an [ALS Recommender](/docs/4/fusion-ai/reference/jobs/als-recommender) job.

**See also [Items-for-user Recommendations](/docs/4/fusion-ai/concepts/boosting/items-for-user) to learn how to configure this recommender type and fetch recommendations.**

<LwTemplate />

## Prerequisites

**Enable recommendations:**

Before creating a Recommend Items for Item stage, enable recommendations.

* **In the Fusion UI** – With Query Workbench open, click **Settings > Enable Recommendations**.
* **Using the REST API** – Use this command to enable recommendations:

  ```bash wrap theme={"dark"}
  curl -u admin:<password> -X PUT http://<hostname>:<port>/api/v1/collections/<collection-name>/features/recommendations -H 'content-type: application/json' -d '{"enabled":true}'
  ```

<Note>
  When you enable recommendations, Fusion creates a query pipeline that already contains this stage, and that is configured for boosting. The query pipeline is `COLLECTION_NAME_items_for_user_recommendations`.
</Note>

## Using live signals

The **Estimate Recent Results** option uses live signals to augment items-for-user recommendations with real-time recommendations.

When this is enabled, Fusion first looks up items (from previously-generated recommendations) that are similar to the new items. If there are none then it looks up similar users (who also interacted with that item) to get a list of recommendations based on the new items. It then combines those new recommendations with the job-based recommendations already generated for that user (if any), to generate a final list of recommendations.

## Configuration

<Tip>
  When entering configuration values in the UI, use *unescaped* characters, such as `\t` for the tab character. When entering configuration values in the API, use *escaped* characters, such as `\\t` for the tab character.
</Tip>

## Configuration

<Tip>
  When entering configuration values in the UI, use *unescaped* characters, such as `\t` for the tab character. When entering configuration values in the API, use *escaped* characters, such as `\\t` for the tab character.
</Tip>

<SchemaParamFields schema={schema} />