Document what overriding field names mean

Goal

Filter table by field names specified with RealmField.

Expected Results

No crashes.

Actual Results

App crashes:

Caused by: java.lang.IllegalArgumentException: Invalid query: field '_id' not found in class 'cards'.
   at io.realm.internal.fields.CachedFieldDescriptor.compileFieldDescription(CachedFieldDescriptor.java:80)
   at io.realm.internal.fields.FieldDescriptor.compileIfNecessary(FieldDescriptor.java:292)
   at io.realm.internal.fields.FieldDescriptor.getColumnIndices(FieldDescriptor.java:185)
   at io.realm.RealmQuery.equalToWithoutThreadValidation(RealmQuery.java:309)
   at io.realm.RealmQuery.in(RealmQuery.java:551)
   at io.realm.RealmQuery.in(RealmQuery.java:531)
   ...

Steps & Code to Reproduce

1. Create a class with a custom table name and a custom field name.
2. Try to query for items using field name passed to RealmField.

Code Sample

Constants replaced with values.

@RealmClass(name = "cards")
public class CardModel implements RealmModel {

    @PrimaryKey
    @Required
    @RealmField(name = "_id")
    private String mKey;

    // getters and setters
}

...

try (final Realm realm = mRealmProvider.get()) {
	final RealmResults<CardModel> all1 = realm.where(CardModel.class)
			.in("mKey", map(keys)) // will NOT crash here
			.findAll();
	final RealmResults<CardModel> all2 = realm.where(CardModel.class)
			.in("_id", map(keys)) // will crash here
			.findAll();
}

Version of Realm and tooling

Realm version(s): 5.0.0

Realm sync feature enabled: no

Android Studio version: 3.0.1

Which Android version and device: API 24, Emulator

[mlykotom]

If it is because you are in the middle of a refactoring searching for the string "mKey" will do the trick (but of course you need to check it isn’t mKey from another class).

This is also why we in a lot of internal tests have the best practice of static fields in the model class:

public class Person extends RealmObject {
  public static final FIELD_NAME = "name";
  public String name;
}

realm.where(Person.class).equalTo(Person.FIELD_NAME, "Jane").findAll();

This is exactly the reason why it should be used in typed queries as well, because when you (accidentally) rename the java field name to e.g. firstName, you’ll still have the proper FIELD_NAME for realm queries.

If you have it this way, then there’s no IDE help and you may easily end up having FIELD_NAME different than java name.

---

Also another use case for using it in queries is, that then you can have (in kotlin) something like this:

const val TYPE_FIELD = "type"

@RealmField(TYPE_FIELD)
private var _type: String

var type: TypeEnum
  get() = _type.toString()
  set(value) {
     _type = TypeEnum.valueOf(value)
  }

And you can still use:

realm
  .where<MyClass>()
  .equals(TYPE_FIELD, TypeEnum.TYPE_A)
  .findAll() 

Which then provides more type-safety, because from code you may access whatever name you added, but in queries you use fields you defined in annotation.

[cmelchior]

Yes, I can see the problem. Honestly, I think a better solution to your problem would be if we started allowing non-polymorphic inheritance, which would allow for a base class with shared fields. So far we have not done that because we feared that not having polymorphism would really trip people up but both our Cocoa binding and ObjectBox do this, so we should probably revisit that decision.

The reason I’m hesitant about “just” allowing queries on both internal and Java names is that it muddles the layers between Java defined names and internal names and we need to enforce that you cannot use an internal name that is already being used in the Java model class.

I’ll need to think a little about this.