Expand Documentation on Type Definitions #224

Closed
spmallette opened this Issue Apr 14, 2013 · 6 comments

Comments

Projects
None yet
6 participants
@spmallette
Member

spmallette commented Apr 14, 2013

The Type Definition Overview wiki page requires more clarity I think. Specifically, greater explanation on:

  • the concept of Unique Types
  • the use of indexed
@zmaril

This comment has been minimized.

Show comment
Hide comment
@zmaril

zmaril Apr 14, 2013

Member

Agreed. Getting Titanium up and running with types was not all that straightforward. I'm writing the documentation for Titanium currently and I saved types for last out of fear. The "unique via direction" idea doesn't intuitively make sense to me yet.

Member

zmaril commented Apr 14, 2013

Agreed. Getting Titanium up and running with types was not all that straightforward. I'm writing the documentation for Titanium currently and I saved types for last out of fear. The "unique via direction" idea doesn't intuitively make sense to me yet.

@wsalembi

This comment has been minimized.

Show comment
Hide comment
@wsalembi

wsalembi Apr 14, 2013

Agreed. I got an exception while creating an elastic search index on a property key: "Only standard index is allowed on non-unique property keys". The point was my index was not intended to be a 'unique' index. Till the point I understood that unique(OUT) means singlevalue and unique(IN) means unique across all vertices. Very confusing.

Agreed. I got an exception while creating an elastic search index on a property key: "Only standard index is allowed on non-unique property keys". The point was my index was not intended to be a 'unique' index. Till the point I understood that unique(OUT) means singlevalue and unique(IN) means unique across all vertices. Very confusing.

@rustyrazorblade

This comment has been minimized.

Show comment
Hide comment
@rustyrazorblade

rustyrazorblade Apr 14, 2013

Personally I think using unique(IN) and unique(OUT) is a strange choice. functional(false) was also weird, but at least didn't use the same term to mean two totally different things. unique is a term used frequently in other databases to indicate that the value is unique in the entire dataset, so at least that was consistent terminology. unique(OUT) is extremely unintuitive that there's a single value of a given key in a vertex.

I'm guessing this is a direct result of how properties are actually stored as vertices? I don't feel that the terms that you expose to people should be a reflection of the implementation, as it results in you needing to change your terminology every time the implementation changes.

On the thunderdome side, we decided to use the same terminology as titan for creating a spec so people wouldn't need to learn something totally new on top of titan, but now we need to maintain a different spec parser on every version bumb. We'll probably end up either dropping the current system or writing a totally new DSL to avoid people having to totally change their spec every time they upgrade titan versions.

See here: https://github.com/StartTheShift/thunderdome/wiki/Spec-Files

Personally I think using unique(IN) and unique(OUT) is a strange choice. functional(false) was also weird, but at least didn't use the same term to mean two totally different things. unique is a term used frequently in other databases to indicate that the value is unique in the entire dataset, so at least that was consistent terminology. unique(OUT) is extremely unintuitive that there's a single value of a given key in a vertex.

I'm guessing this is a direct result of how properties are actually stored as vertices? I don't feel that the terms that you expose to people should be a reflection of the implementation, as it results in you needing to change your terminology every time the implementation changes.

On the thunderdome side, we decided to use the same terminology as titan for creating a spec so people wouldn't need to learn something totally new on top of titan, but now we need to maintain a different spec parser on every version bumb. We'll probably end up either dropping the current system or writing a totally new DSL to avoid people having to totally change their spec every time they upgrade titan versions.

See here: https://github.com/StartTheShift/thunderdome/wiki/Spec-Files

@ghost ghost assigned mbroecheler May 3, 2013

@bytor99999

This comment has been minimized.

Show comment
Hide comment
@bytor99999

bytor99999 Sep 4, 2013

Not sure if this has been addressed. But the Schema definition documentation is extremely confusing. I mean in general I understand the code, but what are we actually defining here. I can't even figure out how to start to define my Vertices. Is schema definition just about properties, or just about edges, or defining everything. Also when should this code to define the schema be run? Each time you start up your application? Just one big confusing documentation.

Thanks

Not sure if this has been addressed. But the Schema definition documentation is extremely confusing. I mean in general I understand the code, but what are we actually defining here. I can't even figure out how to start to define my Vertices. Is schema definition just about properties, or just about edges, or defining everything. Also when should this code to define the schema be run? Each time you start up your application? Just one big confusing documentation.

Thanks

@spmallette

This comment has been minimized.

Show comment
Hide comment
@spmallette

spmallette Sep 4, 2013

Member

what are we actually defining here. I can't even figure out how to start to define my Vertices

You are defining all the property keys (for a vertex or edge) and edge labels you intend to use in your graph, with their explicit data types and constraints. The best practice is to define "everything" and to do so prior to first usage in your graph (e.g. via Element.setProperty), lest the type be defined by default Type Maker:

https://github.com/thinkaurelius/titan/blob/master/titan-core/src/main/java/com/thinkaurelius/titan/graphdb/blueprints/BlueprintsDefaultTypeMaker.java

I think it's smart to set the autotype property to none to disable this feature, which prevents accidental type creation.

Member

spmallette commented Sep 4, 2013

what are we actually defining here. I can't even figure out how to start to define my Vertices

You are defining all the property keys (for a vertex or edge) and edge labels you intend to use in your graph, with their explicit data types and constraints. The best practice is to define "everything" and to do so prior to first usage in your graph (e.g. via Element.setProperty), lest the type be defined by default Type Maker:

https://github.com/thinkaurelius/titan/blob/master/titan-core/src/main/java/com/thinkaurelius/titan/graphdb/blueprints/BlueprintsDefaultTypeMaker.java

I think it's smart to set the autotype property to none to disable this feature, which prevents accidental type creation.

@bytor99999

This comment has been minimized.

Show comment
Hide comment
@bytor99999

bytor99999 Sep 4, 2013

Thanks Stephen, those are the details that I would love to see added to the documentation. I feel it just goes into those little details that those that already knows how it works takes for granted, but those that are new, really would need that information to get going.

Thanks again

Mark

Thanks Stephen, those are the details that I would love to see added to the documentation. I feel it just goes into those little details that those that already knows how it works takes for granted, but those that are new, really would need that information to get going.

Thanks again

Mark

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment