Skip to content

Document parameter behaviour in version 3#280

Merged
susodapop merged 7 commits intonative-query-params-stagingfrom
document-parameters
Nov 15, 2023
Merged

Document parameter behaviour in version 3#280
susodapop merged 7 commits intonative-query-params-stagingfrom
document-parameters

Conversation

@susodapop
Copy link
Contributor

@susodapop susodapop commented Nov 15, 2023 •
edited
Loading

Description

This is a documentation PR for the new parameter support in version 3.

  • README.parameters.md
  • New parameters.py example
  • Update changelog

Jesse Whitehouse added 2 commits November 14, 2023 18:25
Initial documentation work
bd4fd12 
Signed-off-by: Jesse Whitehouse <jesse.whitehouse@databricks.com>
Add details about inline parameters
c1e72bd 
Signed-off-by: Jesse Whitehouse <jesse.whitehouse@databricks.com>
@susodapop susodapop requested a review from benc-db November 15, 2023 00:14
Jesse Whitehouse added 3 commits November 15, 2023 11:58
Significant rewrite for clarity
4f82e3f 
Signed-off-by: Jesse Whitehouse <jesse.whitehouse@databricks.com>
Fix syntax casing
e50d74e 
Signed-off-by: Jesse Whitehouse <jesse.whitehouse@databricks.com>
Add example of parameters usage in native mode
4c2dc9d 
Signed-off-by: Jesse Whitehouse <jesse.whitehouse@databricks.com>
@susodapop
Copy link
Contributor Author

susodapop commented Nov 15, 2023

If you run examples/parameters.py the output looks like this:

EXAMPLE 1
Example 1 result in native mode →        Row(name='Jane', age=30, active=True)
Example 1 result in inline mode →        Row(name='Jane', age=30, active=True)

EXAMPLE 2
Example 2 result with pyformat  →        Row(name='Jane', age=30, active=True)
Example 2 result with named     →        Row(name='Jane', age=30, active=True)

EXAMPLE 3
Example 3 result in native mode →        Row(name='Jane', age=30, active=True)
Example 3 result in inline mode →        Row(name='Jane', age=30, active=True)

EXAMPLE 4
Example 4 inferred result       →        2012-10-15 17:57:18+00:00      12.3456
Example 4 explicit result       →        2012-10-15 12:57:18            12.35

Update changelog
28ce136 
Signed-off-by: Jesse Whitehouse <jesse.whitehouse@databricks.com>
benc-db
benc-db reviewed Nov 15, 2023
View reviewed changes
docs/parameters.md Outdated

**Note**: `%s` is not compliant with PEP-249 and only works due to the specific implementation of our inline renderer.

**Note:** This `%s` syntax overlaps with valid SQL syntax around the usage of `LIKE` DML. For example if your query includes a clause like `WHERE field LIKE '%sequence'`, the parameter inlining function will raise an exception because this string appears to include an inline marker but none is provided.
Copy link
Collaborator

@benc-db benc-db Nov 15, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you should explain in this note that if they switch to using named parameters, we will pass this along to the database, allowing it to be used as expected in the LIKE statements. This might be inferred from the other documentation, but better to be explicit here.

Copy link
Contributor Author

@susodapop susodapop Nov 15, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added!

benc-db
benc-db approved these changes Nov 15, 2023
View reviewed changes
Copy link
Collaborator

@benc-db benc-db left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, only one recommendation to take a look at.

PR add further clarification around %s
eae8352 
Signed-off-by: Jesse Whitehouse <jesse.whitehouse@databricks.com>
@susodapop susodapop merged commit 36e0972 into native-query-params-staging Nov 15, 2023
@susodapop susodapop deleted the document-parameters branch November 15, 2023 18:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@benc-db benc-db benc-db approved these changes

@arikfr arikfr Awaiting requested review from arikfr

@yunbodeng-db yunbodeng-db Awaiting requested review from yunbodeng-db

@andrefurlan-db andrefurlan-db Awaiting requested review from andrefurlan-db andrefurlan-db is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@susodapop @benc-db