Schema Factory Configuration

Solr supports two styles of schema: a managed schema and a manually maintained schema.xml file. When using a managed schema, features such as the Schema API and Schemaless Mode are available. When using schema.xml, the only way changes can be made to Solr’s schema is by manually editing the file.

<schemaFactory> in solrconfig.xml

The <schemaFactory> in solrconfig.xml defines whether your system will use a managed schema or schema.xml.

<config>
  <schemaFactory>
    ...
  </schemaFactory>
</config>

While the "read" features of the Schema API are supported for all schema types, support for making schema modifications programmatically depends on the <schemaFactory/> in use.

Schema Factories

ManagedIndexSchemaFactory

When a <schemaFactory/> is not explicitly declared in a solrconfig.xml file, Solr implicitly uses a ManagedIndexSchemaFactory, which is by default "mutable" (editable) and keeps schema information in a managed-schema.xml file.

Using the Managed Schema is required to be able to use the Schema API to modify your schema. However, using Managed Schema does not mean you are also using Solr in Schemaless Mode (or "schema guessing" mode).

Schemaless mode requires enabling the Managed Schema if it is not already, but full schema guessing requires additional configuration as described in the section Schemaless Mode.

Below is an example of a schemaFactory that reflects Solr’s defaults:

  <schemaFactory class="ManagedIndexSchemaFactory">
    <bool name="mutable">true</bool>
    <str name="managedSchemaResourceName">managed-schema.xml</str>
  </schemaFactory>

The defaults can be overridden by explicitly configuring ManagedIndexSchemaFactory and changing one of the following options:

mutable

Optional

Default: true

Controls whether changes may be made to the schema data. This must be set to true to allow edits to be made with the Schema API.

With the default configuration shown above, you could use the Schema API to modify the schema as much as you want, and then later change the value of mutable to false to "lock" the schema in place and prevent future changes.

managedSchemaResourceName

Optional

Default: managed-schema.xml

The name of the schema file. The name can be anything other than schema.xml, as that name is reserved for the ClassicIndexSchemaFactory.

ClassicIndexSchemaFactory

An alternative to using a managed schema is to explicitly configure a ClassicIndexSchemaFactory. This requires the use of a schema.xml file, and disallows any programatic changes to the Schema at run time. The schema.xml file must be edited manually and is loaded only when the collection is loaded.

  <schemaFactory class="ClassicIndexSchemaFactory"/>

This option takes no parameters.

Changing Schema Factories

Switching from schema.xml to Managed Schema

If you have an existing Solr collection that uses ClassicIndexSchemaFactory, and you wish to convert to use a managed schema, you can simply modify the solrconfig.xml to specify the use of the ManagedIndexSchemaFactory.

Once Solr is restarted and it detects that a schema.xml file exists, but the managedSchemaResourceName file (i.e., “managed-schema.xml”) does not exist, the existing schema.xml file will be renamed to schema.xml.bak and the contents re-written to the managed schema file.

If you look at the resulting file, you’ll see this at the top of the page:

<!-- Solr managed schema - automatically generated - DO NOT EDIT -->

You are now free to use the Schema API to make changes, and remove the schema.xml.bak.

Switching from Managed Schema to schema.xml

If you have started Solr with managed schema enabled and you would like to switch to manually editing a schema.xml file, you should take the following steps:

  1. Rename the managed-schema.xml file to schema.xml.

  2. Modify solrconfig.xml to replace the schemaFactory class.

    1. Remove any ManagedIndexSchemaFactory definition if it exists.

    2. Add a ClassicIndexSchemaFactory definition as shown above

  3. Reload the core(s).

If you are using SolrCloud, you may need to modify the files via ZooKeeper. The bin/solr script provides an easy way to download the files from ZooKeeper and upload them back after edits. See the section ZooKeeper Operations for more information.

To have full control over your schema.xml file, you may also want to disable schema guessing, which allows unknown fields to be added to the schema during indexing. The properties that enable this feature are discussed in the section Schemaless Mode.