Multiple Create: Identify and document the limitations and breaking changes.

[severussundar]

Identify and document all the breaking changes introduced by the feature.

Breaking changes refers to any current setup that is working successfully that would stop working when the feature flag for nested create is switched on.

[ayush3797]

When the nested inserts are enabled:

1. Till now, for queries, we were giving preference to the relationships defined by the user in the config over the relationships defined in the database. This behavior will now change via: https://github.com/Azure/data-api-builder/pull/1997:

• If the relationships defined in config and database are identical, we are good.
• If the relationships defined in config and database are not identical, we throw an exception. This is because for nested insertion, we need to obey the relationship defined in the database.

2. Users can no longer define multiple relationships between same pair of (source, target) entities. This behavior will be implemented via: https://github.com/Azure/data-api-builder/pull/1929. Side note: Even though defining multiple relationships between same source and target entities is allowed when the nested inserts are disabled, this is still a bug because we don't obey multiple relationships. Related issues: https://github.com/Azure/data-api-builder/issues/1859, https://github.com/Azure/data-api-builder/issues/1930, https://github.com/Azure/data-api-builder/issues/1940

[seesharprun]

What is the documentation action item for this task?

[severussundar]

Hey Sidney, the document handed over for multiple create contains information regarding the limitations (scenarios/setups not supported for multiple create operation). Those need to documented in the user facing feature docs to give users an idea of the setups/scenarios supported vs not supported.