Misleading/invalid documentation on SessionContext::sql and SessionConfig::create_logical_plan

[UlfarErl]

The comments for these two functions refer to each other, and the comment for SessionContext::sql indicates that create_logical_plan can be used to avoid DDL / DML statements etc. However, create_logical_plan doesn't restrict such statements (in particular, it is used by SessionContext::sql itself).

https://github.com/apache/arrow-datafusion/blob/00627785718d9d98998021bf44585f32c33af3ea/datafusion/core/src/execution/context.rs#L351C11-L351C11
https://github.com/apache/arrow-datafusion/blob/00627785718d9d98998021bf44585f32c33af3ea/datafusion/core/src/execution/context.rs#L1777

[UlfarErl]

@alamb I spotted this when looking for a read-only LogicalPlan interface, just like the one you were aiming for in issue #4720 (and your PR #4721). Those were closed without any apparent plan for such an interface. It would be great to document (even if planned for the future).

[alamb]

Thanks @UlfarErl -- I agree the comments and API could be improved -- I'll try and improve them this week

The key for "read only" is to not call SessionContext::execute_logical_plan -- so do

SessionContext::create_logical_plan

And then

session_context.state().create_physical_plan

I agree this is not clear from the docs.

[alamb]

Hi @UlfarErl -- I made a PR to update the documentation here #7327

While working on it, it became clear the API is somewhat confusing (as you have already pointed out) #7328 -- PR to fix: #7333