Quarkus Solr

Apache Solr is the open source, multi-modal search platform built on the full-text, vector, and geospatial search capabilities of Apache Lucene. This extension integrates Solr into Quarkus via the SolrJ client library, and provides dev services, Dev UI tooling, and observability out of the box.

It provides the following features:

Automatic Solr dev service for local development and testing
Injected SolrJ SolrClient beans, pre-configured from application.properties
Dev UI card with Solr Admin UI link
MCP tool exposure of all Dev UI operations for use with AI assistants
Native compilation support
Integration with the Quarkus observability stack (health, metrics, logging)

Installation

Add the io.quarkiverse.solr:quarkus-solr extension to your build file.

With Maven:

<dependency>
    <groupId>io.quarkiverse.solr</groupId>
    <artifactId>quarkus-solr</artifactId>
    <version>1.1.0</version>
</dependency>

Using SolrJ in your application

Inject SolrClient wherever you need to interact with Solr:

import org.apache.solr.client.solrj.SolrClient;

@ApplicationScoped
public class SolrService {
    @Inject
    SolrClient solrClient;

    public SolrDocumentList query(String query) throws SolrServerException, IOException {
        SolrQuery solrQuery = new SolrQuery();
        solrQuery.setQuery(query);
        return solrClient.query("my-collection", solrQuery).getResults();
    }
}

The SolrClient bean has @Dependent scope, meaning each injection point gets its own client instance. This is intentional: you can safely apply per-use-case configuration to one injected client without affecting others.

The underlying client type depends on the configuration:

Single node / HTTP: HttpJdkSolrClient — used when a single URL is configured
SolrCloud / ZooKeeper: CloudHttp2SolrClient — used when multiple URLs are configured or quarkus.solr.cloud=true

See the SolrJ documentation for details on querying and indexing documents.

Dev Services for Solr

When running in dev or test mode without a quarkus.solr.url configured, the extension automatically starts a containerised Solr instance via Docker. A collection named dummy is created by default.

# No configuration needed for dev mode — the dev service handles it.
# For production, set:
quarkus.solr.url=http://localhost:8983/solr

See Customize Dev-Service for how to change the image, collection name, and configuration.

SolrCloud

The extension supports SolrCloud (ZooKeeper-based) clusters. Cloud mode activates automatically when you configure multiple node URLs, or you can force it explicitly:

# Multiple nodes — cloud mode is selected automatically
quarkus.solr.url=http://solr1:8983/solr,http://solr2:8983/solr

# Or force cloud mode with a single ZooKeeper URL
quarkus.solr.cloud=true
quarkus.solr.url=zookeeper-host:2181/solr

Key SolrCloud configuration properties:

Property Description

Property	Description
`quarkus.solr.cloud`	Force `CloudHttp2SolrClient` even with a single URL
`quarkus.solr.zk-client-timeout`	ZooKeeper session timeout (ms)
`quarkus.solr.zk-connect-timeout`	ZooKeeper connection timeout (ms)
`quarkus.solr.collection-cache-ttl`	How long to cache collection state (ms)
`quarkus.solr.parallel-cache-refreshes`	Refresh collection cache entries in parallel
`quarkus.solr.parallel-updates`	Send updates to all replicas in parallel
`quarkus.solr.can-use-zk-acls`	Enable ZooKeeper ACL support

quarkus.solr.cloud

Force CloudHttp2SolrClient even with a single URL

quarkus.solr.zk-client-timeout

ZooKeeper session timeout (ms)

quarkus.solr.zk-connect-timeout

ZooKeeper connection timeout (ms)

quarkus.solr.collection-cache-ttl

How long to cache collection state (ms)

quarkus.solr.parallel-cache-refreshes

Refresh collection cache entries in parallel

quarkus.solr.parallel-updates

Send updates to all replicas in parallel

quarkus.solr.can-use-zk-acls

Enable ZooKeeper ACL support

See the Solr ZooKeeper documentation for background on SolrCloud topology.

Dev UI

When running in dev mode, a Solr card is available in the Quarkus Dev UI at /q/dev-ui. Beside general information about the extension, it provides a link to the Solr Admin UI.

See Dev UI & MCP for full details.

Observability

Logging

All Solr interactions are logged at DEBUG level. Request and response details are logged at TRACE level. Enable them in application.properties:

quarkus.log.category."io.quarkiverse.solr".level=DEBUG
# For full request/response details:
quarkus.log.category."io.quarkiverse.solr".level=TRACE

Health

If quarkus-smallrye-health is on the classpath, a readiness check is automatically registered. It verifies that the Solr instance is reachable. The check can be disabled:

quarkus.solr.health-enabled=false

Metrics

If quarkus-micrometer-registry-prometheus is on the classpath, timers and counters are automatically registered for all Solr requests.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.solr.health-enabled` Is solr health check enabled Environment variable: `QUARKUS_SOLR_HEALTH_ENABLED`	boolean	`true`
`quarkus.solr.devservices.enabled` If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a solr instance when running in Dev or Test mode and when Docker is running. Environment variable: `QUARKUS_SOLR_DEVSERVICES_ENABLED`	boolean	`true`
`quarkus.solr.devservices.image-name` The container image name to use, for container based DevServices providers. If not set, the default solr image in the version of solrj will be used Environment variable: `QUARKUS_SOLR_DEVSERVICES_IMAGE_NAME`	string
`quarkus.solr.devservices.port` Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_SOLR_DEVSERVICES_PORT`	int
`quarkus.solr.devservices.collection` The name of the collection to be created in Solr If not defined, a collection names "dummy" will be created Environment variable: `QUARKUS_SOLR_DEVSERVICES_COLLECTION`	string
`quarkus.solr.devservices.configuration` Custom configuration to be used. Must be a directory on the classpath containing at least a solrconfig.xml If not set, default configuration of Solr docker container is used Environment variable: `QUARKUS_SOLR_DEVSERVICES_CONFIGURATION`	string
`quarkus.solr.devservices.service-name` The value of the label attached to the started container. This property is used when `shared` is set to `true`. In this case, before starting a container, Dev Services looks for a container with the `quarkus-dev-service-solr` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the `quarkus-dev-service-solr` label set to the specified value. This property is used when you need multiple shared Solr instances. Environment variable: `QUARKUS_SOLR_DEVSERVICES_SERVICE_NAME`	string	`solr`
`quarkus.solr.devservices.shared` Indicates if the instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. The discovery uses the `quarkus-dev-service-solr` label. The value is configured using the `service-name` property. Container sharing is only used in dev mode. Environment variable: `QUARKUS_SOLR_DEVSERVICES_SHARED`	boolean	`true`
`quarkus.solr.url` One or more Solr URLs, which the client then uses to send HTTP requests to Solr. These URLS must point to the root Solr path (i.e. "/solr"). If multiple URLs are configured, it is assumed that Solr Cloud Mode is used and these URLs are used to fetch information about the layout and health of the Solr cluster. If only one URL is defined, the URLs is used to send user-provided requests using `org.apache.solr.client.solrj.impl.HttpJdkSolrClient HttpJdkSolrClient`. Environment variable: `QUARKUS_SOLR_URL`	list of string	required
`quarkus.solr.default-collection` Default collection to be used Most SolrClient methods allow users to specify the collection or core they wish to query, etc. as a String parameter. However, continually specifying this parameter can become tedious, especially for users who always work with the same collection. Users can avoid this pattern by specifying a "default" collection If specified SolrClients will use this default for making requests whenever a collection or core is needed (and no overriding value is specified) Environment variable: `QUARKUS_SOLR_DEFAULT_COLLECTION`	string
`quarkus.solr.http1` Should HTTP 1.1 be used instead of HTTP/2? If not set, HTTP/2 is used by default Environment variable: `QUARKUS_SOLR_HTTP1`	boolean	`false`
`quarkus.solr.request-timeout` Request timeout in milliseconds If not set, idle timeout is used Environment variable: `QUARKUS_SOLR_REQUEST_TIMEOUT`	long
`quarkus.solr.idle-timeout` Idle timeout in milliseconds If not set, `org.apache.solr.client.solrj.impl.SolrHttpConstants#DEFAULT_SO_TIMEOUT SolrJ’s default value` is used Environment variable: `QUARKUS_SOLR_IDLE_TIMEOUT`	long
`quarkus.solr.connection-timeout` Connection timeout in milliseconds If not set, `org.apache.solr.client.solrj.impl.SolrHttpConstants#DEFAULT_CONNECT_TIMEOUT SolrJ’s default value` is used Environment variable: `QUARKUS_SOLR_CONNECTION_TIMEOUT`	long
`quarkus.solr.follow-redirects` Should the client follow redirects? If not set, redirect are not followed Environment variable: `QUARKUS_SOLR_FOLLOW_REDIRECTS`	boolean	`false`
`quarkus.solr.max-connections-per-host` Maximal number of connections per host If not set, `org.apache.solr.client.solrj.impl.SolrHttpConstants#DEFAULT_MAXCONNECTIONS SolrJ’s default value` is used Environment variable: `QUARKUS_SOLR_MAX_CONNECTIONS_PER_HOST`	int
`quarkus.solr.basic-auth.username` The username Environment variable: `QUARKUS_SOLR_BASIC_AUTH_USERNAME`	string	required
`quarkus.solr.basic-auth.password` The password Environment variable: `QUARKUS_SOLR_BASIC_AUTH_PASSWORD`	string	required
`quarkus.solr.proxy.host` The proxy host Environment variable: `QUARKUS_SOLR_PROXY_HOST`	string	required
`quarkus.solr.proxy.port` The proxy port Environment variable: `QUARKUS_SOLR_PROXY_PORT`	int	`0`
`quarkus.solr.proxy.socks4` Is this a socks4 proxy? Environment variable: `QUARKUS_SOLR_PROXY_SOCKS4`	boolean	`false`
`quarkus.solr.proxy.secure` Is this proxy using HTTPS Environment variable: `QUARKUS_SOLR_PROXY_SECURE`	boolean	`false`
`quarkus.solr.cloud` Force SolrCloud mode If set, it is assumed that Solr Cloud Mode is used even if only one `url()` is defined Environment variable: `QUARKUS_SOLR_CLOUD`	boolean	`false`
`quarkus.solr.zk-client-timeout` Zookeeper client timeout in milliseconds Only relevant if Solr Cloud Mode is used even. If not set, `org.apache.solr.client.solrj.impl.SolrZkClientTimeout#DEFAULT_ZK_CLIENT_TIMEOUT SolrJ’s default value` is used Environment variable: `QUARKUS_SOLR_ZK_CLIENT_TIMEOUT`	int
`quarkus.solr.zk-connect-timeout` Zookeeper connection timeout in milliseconds Only relevant if Solr Cloud Mode is used. If not set, `org.apache.solr.client.solrj.impl.SolrZkClientTimeout#DEFAULT_ZK_CONNECT_TIMEOUT SolrJ’s default value` is used Environment variable: `QUARKUS_SOLR_ZK_CONNECT_TIMEOUT`	int
`quarkus.solr.can-use-zk-ac-ls` Can Zookeepers ACL be used Only relevant if Solr Cloud Mode is used. See documentation for details. If not set,SolrJ’s default value (true) is used. Environment variable: `QUARKUS_SOLR_CAN_USE_ZK_AC_LS`	boolean
`quarkus.solr.collection-cache-ttl` Cache ttl for cached objects in seconds Only relevant if Solr Cloud Mode is used. If not set,SolrJ’s default value (60s) is used. Environment variable: `QUARKUS_SOLR_COLLECTION_CACHE_TTL`	int
`quarkus.solr.parallel-cache-refreshes` Number of parallel collection state refresh operations to run in parallel Only relevant if Solr Cloud Mode is used. If not set,SolrJ’s default value (5) is used. Environment variable: `QUARKUS_SOLR_PARALLEL_CACHE_REFRESHES`	int
`quarkus.solr.retry-expiry-time` Time to wait to re-fetch the state after getting the same state version from Zookeeper in milliseconds Only relevant if Solr Cloud Mode is used. If not set,SolrJ’s default value (3000) is used. Environment variable: `QUARKUS_SOLR_RETRY_EXPIRY_TIME`	long
`quarkus.solr.parallel-updates` Should shard updates be sent in parallel Only relevant if Solr Cloud Mode is used. When an UpdateRequest affects multiple shards, CloudSolrClient splits it up and sends a request to each affected shard. This setting chooses whether those sub-requests are sent serially or in parallel. If not set,SolrJ’s default value ('true') is used. Environment variable: `QUARKUS_SOLR_PARALLEL_UPDATES`	boolean

Configuration property

Type

Default

quarkus.solr.health-enabled

Is solr health check enabled

Environment variable: QUARKUS_SOLR_HEALTH_ENABLED

boolean

true

quarkus.solr.devservices.enabled

If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present.

When DevServices is enabled Quarkus will attempt to automatically configure and start a solr instance when running in Dev or Test mode and when Docker is running.

Environment variable: QUARKUS_SOLR_DEVSERVICES_ENABLED

boolean

true

quarkus.solr.devservices.image-name

The container image name to use, for container based DevServices providers.

If not set, the default solr image in the version of solrj will be used

Environment variable: QUARKUS_SOLR_DEVSERVICES_IMAGE_NAME

string

quarkus.solr.devservices.port

Optional fixed port the dev service will listen to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_SOLR_DEVSERVICES_PORT

int

quarkus.solr.devservices.collection

The name of the collection to be created in Solr

If not defined, a collection names "dummy" will be created

Environment variable: QUARKUS_SOLR_DEVSERVICES_COLLECTION

string

quarkus.solr.devservices.configuration

Custom configuration to be used. Must be a directory on the classpath containing at least a solrconfig.xml

If not set, default configuration of Solr docker container is used

Environment variable: QUARKUS_SOLR_DEVSERVICES_CONFIGURATION

string

quarkus.solr.devservices.service-name

The value of the label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, Dev Services looks for a container with the quarkus-dev-service-solr label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the quarkus-dev-service-solr label set to the specified value.

This property is used when you need multiple shared Solr instances.

Environment variable: QUARKUS_SOLR_DEVSERVICES_SERVICE_NAME

string

solr

quarkus.solr.devservices.shared

Indicates if the instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.

The discovery uses the quarkus-dev-service-solr label. The value is configured using the service-name property.

Container sharing is only used in dev mode.

Environment variable: QUARKUS_SOLR_DEVSERVICES_SHARED

boolean

true

quarkus.solr.url

One or more Solr URLs, which the client then uses to send HTTP requests to Solr.

These URLS must point to the root Solr path (i.e. "/solr"). If multiple URLs are configured, it is assumed that Solr Cloud Mode is used and these URLs are used to fetch information about the layout and health of the Solr cluster.

If only one URL is defined, the URLs is used to send user-provided requests using org.apache.solr.client.solrj.impl.HttpJdkSolrClient HttpJdkSolrClient.

Environment variable: QUARKUS_SOLR_URL

list of string

required

quarkus.solr.default-collection

Default collection to be used

Most SolrClient methods allow users to specify the collection or core they wish to query, etc. as a String parameter. However, continually specifying this parameter can become tedious, especially for users who always work with the same collection.

Users can avoid this pattern by specifying a "default" collection If specified SolrClients will use this default for making requests whenever a collection or core is needed (and no overriding value is specified)

Environment variable: QUARKUS_SOLR_DEFAULT_COLLECTION

string

quarkus.solr.http1

Should HTTP 1.1 be used instead of HTTP/2?

If not set, HTTP/2 is used by default

Environment variable: QUARKUS_SOLR_HTTP1

boolean

false

quarkus.solr.request-timeout

Request timeout in milliseconds

If not set, idle timeout is used

Environment variable: QUARKUS_SOLR_REQUEST_TIMEOUT

long

quarkus.solr.idle-timeout

Idle timeout in milliseconds

If not set, org.apache.solr.client.solrj.impl.SolrHttpConstants#DEFAULT_SO_TIMEOUT SolrJ’s default value is used

Environment variable: QUARKUS_SOLR_IDLE_TIMEOUT

long

quarkus.solr.connection-timeout

Connection timeout in milliseconds

If not set, org.apache.solr.client.solrj.impl.SolrHttpConstants#DEFAULT_CONNECT_TIMEOUT SolrJ’s default value is used

Environment variable: QUARKUS_SOLR_CONNECTION_TIMEOUT

long

quarkus.solr.follow-redirects

Should the client follow redirects?

If not set, redirect are not followed

Environment variable: QUARKUS_SOLR_FOLLOW_REDIRECTS

boolean

false

quarkus.solr.max-connections-per-host

Maximal number of connections per host

If not set, org.apache.solr.client.solrj.impl.SolrHttpConstants#DEFAULT_MAXCONNECTIONS SolrJ’s default value is used

Environment variable: QUARKUS_SOLR_MAX_CONNECTIONS_PER_HOST

int

quarkus.solr.basic-auth.username

The username

Environment variable: QUARKUS_SOLR_BASIC_AUTH_USERNAME

string

required

quarkus.solr.basic-auth.password

The password

Environment variable: QUARKUS_SOLR_BASIC_AUTH_PASSWORD

string

required

quarkus.solr.proxy.host

The proxy host

Environment variable: QUARKUS_SOLR_PROXY_HOST

string

required

quarkus.solr.proxy.port

The proxy port

Environment variable: QUARKUS_SOLR_PROXY_PORT

int

0

quarkus.solr.proxy.socks4

Is this a socks4 proxy?

Environment variable: QUARKUS_SOLR_PROXY_SOCKS4

boolean

false

quarkus.solr.proxy.secure

Is this proxy using HTTPS

Environment variable: QUARKUS_SOLR_PROXY_SECURE

boolean

false

quarkus.solr.cloud

Force SolrCloud mode

If set, it is assumed that Solr Cloud Mode is used even if only one url() is defined

Environment variable: QUARKUS_SOLR_CLOUD

boolean

false

quarkus.solr.zk-client-timeout

Zookeeper client timeout in milliseconds

Only relevant if Solr Cloud Mode is used even. If not set, org.apache.solr.client.solrj.impl.SolrZkClientTimeout#DEFAULT_ZK_CLIENT_TIMEOUT SolrJ’s default value is used

Environment variable: QUARKUS_SOLR_ZK_CLIENT_TIMEOUT

int

quarkus.solr.zk-connect-timeout

Zookeeper connection timeout in milliseconds

Only relevant if Solr Cloud Mode is used. If not set, org.apache.solr.client.solrj.impl.SolrZkClientTimeout#DEFAULT_ZK_CONNECT_TIMEOUT SolrJ’s default value is used

Environment variable: QUARKUS_SOLR_ZK_CONNECT_TIMEOUT

int

quarkus.solr.can-use-zk-ac-ls

Can Zookeepers ACL be used

Only relevant if Solr Cloud Mode is used. See documentation for details. If not set,SolrJ’s default value (true) is used.

Environment variable: QUARKUS_SOLR_CAN_USE_ZK_AC_LS

boolean

quarkus.solr.collection-cache-ttl

Cache ttl for cached objects in seconds

Only relevant if Solr Cloud Mode is used. If not set,SolrJ’s default value (60s) is used.

Environment variable: QUARKUS_SOLR_COLLECTION_CACHE_TTL

int

quarkus.solr.parallel-cache-refreshes

Number of parallel collection state refresh operations to run in parallel

Only relevant if Solr Cloud Mode is used. If not set,SolrJ’s default value (5) is used.

Environment variable: QUARKUS_SOLR_PARALLEL_CACHE_REFRESHES

int

quarkus.solr.retry-expiry-time

Time to wait to re-fetch the state after getting the same state version from Zookeeper in milliseconds

Only relevant if Solr Cloud Mode is used. If not set,SolrJ’s default value (3000) is used.

Environment variable: QUARKUS_SOLR_RETRY_EXPIRY_TIME

long

quarkus.solr.parallel-updates

Should shard updates be sent in parallel

Only relevant if Solr Cloud Mode is used. When an UpdateRequest affects multiple shards, CloudSolrClient splits it up and sends a request to each affected shard. This setting chooses whether those sub-requests are sent serially or in parallel. If not set,SolrJ’s default value ('true') is used.

Environment variable: QUARKUS_SOLR_PARALLEL_UPDATES

boolean