I sincerely hope someone from the Tulip team will read this since I think it’s about something that should have been done a long time ago. Creating the content I described below is, I think, important and would impact quite positively the developers (and more broadly customers)’ experience with Tulip integration.
I was recently working with the Tulip API and using the _sequenceNumber field. I was looking for some documentation on it but was very surprised to see that it is only present on only two pages (that I couldn’t find by other means) according to a Google site:tulip.co _sequenceNumber search:
- Table optimization for scalability and performance
- Increment or decrement a field in a Tulip Table record
… which is a real shame because this field is incredibly useful when doing data import/export/synchronization (a recurring need for customers in my experience).
This lead me to the realization that, I think, Tulip tables’ technical aspects are greatly under-documented. Many of the things I know about tables were painfully discovered by trial-and-error/reverse engineering…
I think it would be very valuable (and quite honestly more than time) for developers to have a new documentation page describing fundamental technical Tulip table essentials, such as:
- record IDs (of Text type, must be unique, must be filled, has the fixed UID “id”, leading and trailing whitespace chars apparently trimmed off on record creation)
- add and update metadata (
_createdAtand_updatedAtfields, managed by Tulip, always filled) - sequence number (
_sequenceNumberfield, always filled, always present but not displayed in Tulip tables view, starts at 1, incremented by 1 at each record creation, never reset, cannot be modified (I guess?)) - all other columns are nullable
- a table can contain a maximum of 200 columns (including archived columns,
_createdAt,_updatedAt, and maybe alsoid?) - table UID (17 random upper letters, lower letters and digits, never changes, new one generated on table import?)
- field UID (random 5 lower and digit prefix, followed by an underscore, followed by a lowercase version of the first name ever given to the field (removes special characters, with best-effort word boundary detection using spaces and uppercase letters))
- it would be quite appropriate to warn the user that the first name ever given to a table field should ideally be as “correct” / clean as possible since it will be there forever!
- and other topics such as:
- max record count in a table?
- warning about discouraged use of linked records?
- the 10’000 records limit when importing CSV data (but no limit on table export)?
- a link to the page that describes what happens during table export/import?
- the fact that table UIDs seem to be automatically “translated” to the UID of the previously exported/imported corresponding table when exporting/importing functions/automations? I’m not sure I remember this correctly, but I’m positive that this behavior exists.
- any useful advice (or link to them) to deal with the most annoying limitations (100-record limit when reading with Tulip API, Tulip data synchronization using
_sequenceNumberetc.) - … you name it
I think a new page under the Tables category would be very appropriate, since the content in Tables is more “user-focused” and already quite long. And as can be seen above, there are more than enough things to explain to justify a dedicated page.
I know I’m repeating myself (and probably being inappropriately insistent) but given how much time I could have saved knowing all these things in advance, I cannot possibly overstate how important it is to have that documented thoroughly. Knowing all this would have greatly facilitated Tulip integration and avoided customer frustration (and probably several meeting hours trying to figure out these behaviors and how to deal with them).
Any thought about this is more than welcome.