Select a documentation version: <button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">18.4.0</button>

- [Current (18.4.0)](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/ai/solr-search.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/ai/solr-search.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.3.0/docs/ai/solr-search.md.txt)
- [17.10.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.10.0/docs/ai/solr-search.md.txt)
- [17.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.9.0/docs/ai/solr-search.md.txt)

<br />

You can access and search data stored in [Apache Solr](https://solr.apache.org/) using the external search integration in AlloyDB Omni. This integration lets you offload intensive full-text search, complex query parsing, and advanced faceting workloads from your operational database to Solr, improving query latency and overall system throughput.

<br />

> [!NOTE]
> **Note:** AlloyDB Omni using RPM and the AlloyDB Omni RPM orchestrator are not supported.

## Before you begin

Before you begin, complete the following:

- [Install AlloyDB Omni using the container orchestrator](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/deploy-kubernetes.md.txt).
- [Deploy and
  run Apache Solr in production](https://solr.apache.org/guide/solr/latest/deployment-guide/taking-solr-to-production.html).

## Store Solr credentials in Secret Manager

AlloyDB Omni stores and reads your Solr credentials from
Secret Manager. For Basic HTTP authentication, the value of the
secret in Secret Manager must be a base64-encoded string in the
format `username:password`. For more information on how to use
Secret Manager, see
[Create and access a secret using Secret Manager](https://docs.cloud.google.com/secret-manager/docs/create-secret-quickstart.md.txt).

Make sure that the service account that AlloyDB Omni uses has
the `secretmanager.secretAccessor` permission to read the secret from
Secret Manager. For more information, see
[Manage access to secrets](https://docs.cloud.google.com/secret-manager/docs/manage-access-to-secrets.md.txt).

To configure the service account key secret on your Kubernetes database cluster,
see [Create a Kubernetes secret using the service account key](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/install-with-alloydb-ai.md.txt#create-key)
and [Create a database cluster with AlloyDB AI](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/install-with-alloydb-ai.md.txt#enable-alloydb-ai).


## Enable and configure the `external_search_fdw` extension

To start your integration with Solr, configure access to your Solr cluster through a foreign data server.

1. Connect to your database and enable the extension:

   ```sql
   CREATE EXTENSION external_search_fdw;
   ```
2. Create a foreign server:

   ```sql
   CREATE SERVER SOLR_SERVER_NAME
   FOREIGN DATA WRAPPER external_search_fdw
   OPTIONS (
     server 'SOLR_SERVER_HOST_PORT',
     search_provider 'solr',
     auth_mode 'secret_manager',
     auth_method 'AUTH_METHOD',
     secret_path 'SECRET_PATH'
   );
   ```

   Replace the following variables:
   - `SOLR_SERVER_NAME`:
     name for your foreign data server. For example,
     `solr`.

   - `SOLR_SERVER_HOST_PORT`:
     Public-facing URL for your Solr cluster. For example,
     `https://node1.solr.test.com:8983`.

   - `AUTH_METHOD`: type of
     authentication to use. For example, `Basic`.

   - `SECRET_PATH`:
     Secret Manager path to your Solr authentication
     credentials. For example,
     `projects/PROJECT_ID/secrets/apikey/versions/1`.

3. Define the user mapping for the Solr server:

   ```sql
   CREATE USER MAPPING FOR CURRENT_USER
   SERVER SOLR_SERVER_NAME;
   ```
4. Map the schema of your Solr collection to a PostgreSQL foreign table.

   ```sql
   CREATE FOREIGN TABLE SOLR_FD_TABLE(
       metadata external_search_fdw_schema.OpaqueMetadata,
       SOLR_FIELDS)
          SERVER SOLR_SERVER_NAME
          OPTIONS(
               remote_table_name 'SOLR_COLLECTION_NAME',
               unique_key_sort_suffix 'UNIQUE_KEY_SORT_SUFFIX'
   );
   ```

   Replace the following variables:
   - `SOLR_FD_TABLE`: the name of the foreign data table that represents your Solr table. For example, `my-fd-solr-table`.

   - `SOLR_FIELDS`: a comma-separated list where each entry follows the format `solr_field_name PG_DATA_TYPE`.
     For a list of supported Solr data types and their corresponding
     PostgreSQL types, see [Supported data types](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/elastic-search.md.txt#supported-data-types).

   - `UNIQUE_KEY_SORT_SUFFIX`: (Optional) the unique key field in Solr, or a comma-separated list of multiple fields with their sort orders---for example, `myid0 ASC, myid1 DESC`, used for pagination. Defaults to `id`.

   - `PG_DATA_TYPE`: the PostgreSQL type that you want to map it to. For example:

     - `TEXT` for string data.
     - `INTEGER` for numeric data.
   - `SOLR_COLLECTION_NAME`: the name of your Solr collection. For example, `my-solr-collection`.

## Query your Solr data

AlloyDB Omni converts SQL queries to
Solr REST API queries.

### Standard SQL queries

For the search expression, you can use standard SQL with [Lucene syntax](https://solr.apache.org/guide/solr/latest/query-guide/standard-query-parser.html).

```sql
SELECT id, body
FROM SOLR_FD_TABLE
WHERE FILTER
ORDER BY metadata <@> 'QUERY';
```

Replace the following variables:

- `SOLR_FD_TABLE`:
  name of the foreign data table that represents your Solr table. For
  example, `my-fd-solr-table`.

- `FILTER`: (Optional) filter to
  apply to your Solr query. For example, `AND qubits < 105`.

- `QUERY`: query to send to
  Solr. For example, `body:database`.

## Query DSL

For advanced use cases --- such as implementing nested queries, customized sorting, or complex filtering --- use Solr JSON-style [Query DSL](https://solr.apache.org/guide/solr/latest/query-guide/json-query-dsl.html).

```sql
SELECT id, title
FROM SOLR_FD_TABLE
ORDER BY metadata <@> $${
  "query": "title:solr",
  "filter": ["category:software", "inStock:true"],
  "sort": "price desc"
}$$
LIMIT 1;
```

Replace `SOLR_FD_TABLE` with
the name of the foreign data table that represents your Solr table. For
example, `my-fd-solr-table`.

> [!NOTE]
> **Note:** For Query DSL, you only need to propagate the `query`, `filter`, and `sort` expressions.

### Hybrid searches

To perform a
[hybrid search](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/ai/run-hybrid-vector-similarity-search.md.txt#hybrid-search)
on your Solr data, join Solr token search results with AlloyDB Omni vector search results.

```sql
SELECT *
FROM ai.hybrid_search(
  ARRAY[
    '{"limit": LIMIT,
      "weight": WEIGHT,
      "table_name": "SOLR_FD_TABLE",
      "key_column": "id",
      "query_text_input": "QUERY"}'::jsonb
  ])
ORDER BY score DESC;
```

Replace the following variables:

- `LIMIT`: number of results to
  return. For example, `10`.

- `WEIGHT`: contribution of this
  search entry to the overall Reciprocal Rank Fusion (RRF). For example,
  `0.5`. If you don't provide weights, they are distributed evenly. For more
  information, see [Hybrid search function parameters](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/reference/ai/hybrid-search-function-parameters).

- `SOLR_FD_TABLE`:
  name of the foreign data table that represents your Solr table. For
  example, `my-fd-solr-table`.

- `QUERY`: query to send to
  Solr. For example, `body:database`.

> [!NOTE]
> **Note:** The `data_type` field in the search entry, as well as the `id_type`, `fusion_algorithm`, and `include_json_output` function parameters, are optional and use default values. For example, the fusion algorithm defaults to `RRF`.

## Troubleshooting

If you encounter authentication or connectivity issues when querying your Solr
cluster, check the following:

- HTTP 401 or 403 authentication errors: verify that your Solr secret in Secret Manager contains a base64-encoded string in the format `username:password` and that the service account that AlloyDB Omni uses has the `secretmanager.secretAccessor` permission.
- Connection timeouts: verify network rules and firewall configuration between AlloyDB Omni and your Solr endpoint.

## Limitations

- Read-only: AlloyDB Omni reads, but doesn't write to, Solr data.
- Data management: AlloyDB Omni doesn't automatically index your database data into Solr. You're responsible for populating your Solr collections and maintaining consistency between the data in AlloyDB Omni and the indexed data in Solr.
- Schema management: AlloyDB Omni doesn't automatically synchronize schemas with Solr. If your Solr collection schema changes, manually update the schema of the corresponding PostgreSQL foreign table.
- Unsupported types: specialized Solr types, such as geospatial types, aren't supported.
- Stable sorting: for pagination to work correctly, Solr requires a unique key in the sort expression. By default, the `id` field is used. To specify a custom field, or a comma-separated list of multiple fields along with their individual sort orders, use the `unique_key_sort_suffix` option when you create the foreign table. For example, specify `myid0 ASC, myid1 DESC`.

## What's next

- Learn how to [Access OpenSearch data](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/ai/opensearch.md.txt).
- Learn how to [Access Elasticsearch data](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/elastic-search.md.txt).
- Learn how to [Run a hybrid vector similarity search](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/ai/run-hybrid-vector-similarity-search.md.txt).