This section describes how to add, change, disable and enable, and show the Avro schema in your store.
Avro schema is defined in a flat-text file, and then added to
the store using the command line interface. For example,
suppose you have schema defined in a file called
my_schema.avsc. Then (assuming your store is
running) you start your command line interface and add the
schema like this:
> java -jar <kvhome>/lib/kvstore.jar runadmin -port <port> -host <host> kv-> ddl add-schema -file my_schema.avsc
Note that when adding schema to the store, some error
checking is performed to ensure that the schema is
correctly formed. Errors are problems that must be
addressed before the schema can be added to the store.
Warnings are problems that should be addressed, but are not
so serious that the CLI refuses to add the schema.
However, to add schema with Warnings, you must use the
-force switch.
As of this release, the only Error that can be produced is if a field's default value does not conform to the field's type. That is, if the schema provides an integer as the default value where a string is required.
As of this release, the only Warning that can be produced is if the schema does not provide a default value for every field in the schema. Default values are required if you ever want to change (evolve) the schema. But in all other cases, the lack of a default value does no harm.
To change (evolve) existing schema, use the -evolve
flag:
kv-> ddl add-schema -file my_schema.avsc -evolve
Note that when changing schema in the store, some error checking is performed to ensure that schema evolution can be performed correctly. This error checking consists of comparing the new schema to all currently enabled versions of that schema.
This error checking can result in either Errors or Warnings. Errors are fatal problems that must be addressed before the modified schema can be added to the store. Errors represent situations where data written with an old version of the schema cannot be read by clients using a new version of the schema.
Possible errors are:
A field is added without a default value.
The size of a fixed type is changed.
An enum symbol is removed.
A union type is removed or, equivalently, a union type is changed to a non-union type and the new type is not the sole type in the old union.
A change to a field's type (specifically to a different type name) is considered an error except when it is a type promotion, as defined by the Avro spec. And even a type promotion is a warning; see below. Another exception is changing from a non-union to a union; see below.
Warnings are problems that can be avoided using a a two-phase upgrade process. In a two-phase upgrade, all clients begin using the schema only for reading in phase I (the old schema is still used for writing), and then use the new schema for both reading and writing in phase II. Phase II may not be begun until phase I is complete; that is, no client may use the new schema for writing until all clients are using it for reading.
Possible Warnings are:
A field is deleted in the new schema when it does not contain a default value in the old schema.
An enum symbol is added.
A union type is added or, equivalently, a non-union type is changed to a union that includes the original type and additional types.
A field's type is promoted, as defined by the Avro spec. Type promotions are: int to long, float or double; long to float or double; float to double.
You cannot delete schema, but you can disable it:
kv-> ddl disable-schema -name avro.MyInfo.1
To enable schema that has been disabled:
kv-> ddl enable-schema -name avro.MyInfo.1